Traitcapture API specification v3§

Preamble§

Only requests under the uri path traitcapture.org/api/v3 will be served.

Requests made can include the .json extension, however it is not neccesary (or encouraged). Instead, it is encouraged to include the datatype in the request Accept header.

Serialised mappings returned by requests are dependent on the type specified by the request (default is application/json).

Referenced resources include the uri to access them by their unique id.

The List Resource accessors return values as an array of objects in the resources field, and use cursor and count request arguments to chunk up returns. The max count is 500 for rate limiting. These also contain fields for the total number of resources, the next cursor number and a uri to access the next set of data.

The instance resource accessors accept multiple ids separated by either a comma (“,”) or a plus symbol (“+”). This will return data in the same format as a List resource accessor and accepts the same request arguments for cursor and count.

Common Fields§

id
a 24-digit hexadecimal string which is the ObjectId (primary key) of the resource in the database.
uri
the endpoint where this resource can be accessed.
view
a url intended to be accessed by a user through a web browser.
name
a unicode string that is generally assumed (but not always guaranteed) to be unique for that resource type.
resources
an array of the resources requested.
_total_count
an integer for the total number of resources available for the request.
_next_cursor
an integer for the cursor for the next set of data.
_next
uri that links to the next set of data.
_cursor
an integer for the current cursor.

Discover Resource types§

endpoint
/api/v3
methods
GET
return
array of maps of resource type names, their endpoints and field descriptions.
Discovery Example Response (truncated to 2 items)§
[
  {
    "description": "required data for viewing a time lapse (timestream)",
    "fields": {
      "access": "Integer, access level for this resource",
      "description": "String, notes and extra information (text indexed, never sorted)",
      "end_datetime": "end time (iso8601), may include timezone",
      "height": "height of timestream in pixels",
      "height_hires": "same as height for the high resolution images",
      "id": "ObjectId, Globally unique resource id",
      "image_type": "case sensitive file extension (default JPG)",
      "isUtc": "DEPRECATED flag for whether the timestream is using UTC time",
      "location_string": "location of capture",
      "name": "String, indexed, user friendly name. Must be unique for the resource/collection",
      "ongoing": "boolean value indicating whether this has finished or not",
      "owner": "Reference, a User resource that has ownership of this resource",
      "period": "amount of time between images",
      "root": "webroot for the location of the images",
      "root_hires": "webroot to access the high resolution images",
      "start_datetime": "start time (iso8601), may include timezone",
      "timezone": "DEPRECATED time zone as an integer",
      "ts_id": "extra indexed id field (unique)",
      "width": "width of timestream in pixels",
      "width_hires": "same as width for the high resolution images"
    },
    "name": "timestream",
    "uri": "/api/v3/timestream"
  },
  {
    "description": "metadata for an experiment",
    "fields": {
      "access": "Integer, access level for this resource",
      "description": "String, notes and extra information (text indexed, never sorted)",
      "end_datetime": "end time (iso8601), may include timezone",
      "expt_id": "extra indexed id field (unique)",
      "id": "ObjectId, Globally unique resource id",
      "is_supersite": "boolean value indicating whether this experiment and its timestreams are a part of TERNs data",
      "location_string": "location of experiment",
      "name": "String, indexed, user friendly name. Must be unique for the resource/collection",
      "ongoing": "boolean value indicating whether this has finished or not",
      "owner": "Reference, a User resource that has ownership of this resource",
      "spp": "species being studied",
      "start_datetime": "start time (iso8601), may include timezone",
      "timestreams": "list of timestreams that are in this experiment"
    },
    "name": "experiment",
    "uri": "/api/v3/experiment"
  }
]

Create or List all available resources§

endpoints
  • /api/v3/<resource type>
methods
  • GET
  • POST
GET error codes
  • 200: OK
  • 404: Resource/s not found, or invalid authentication for resource/s
POST error codes
  • 200: OK (no ‘errors’ field)
  • 401: no permission to create resources of this type
  • 405: no creation form for this resource type
  • 400: invalid/missing data was/wasn’t provided and is required
  • 409: provided field is not unique and the spec requires uniqueness
  • 500: unknown error
List Example Response§
{
  "_count": 2,
  "_cursor": 0,
  "_next": "/api/v3/experiment?cursor=2&count=2",
  "_next_cursor": 2,
  "_total_count": 28,
  "resources": [
    {
      "access": 0,
      "description": "Description",
      "end_datetime": "2015-09-11T03:17:00",
      "expt_id": "FNQR-DDC",
      "id": "55f249c4d131446fcca19a9c",
      "is_supersite": true,
      "location_string": "Daintree Discovery Centre",
      "name": "FNQR-Daintree",
      "ongoing": false,
      "owner": {
        "id": "5587bd8cd1314423b7aac947",
        "name": "Gareth Dunstone"
      },
      "spp": "Varied",
      "start_datetime": "2015-09-11T03:17:00",
      "timestreams": [
        {
          "id": "55f247c4d131446e8805cc58",
          "name": "fnqr-daintree-overstory-nadir-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247c4d131446e8805cc58"
        },
        {
          "id": "55f247c4d131446e8805cc59",
          "name": "fnqr-daintree-overstory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247c4d131446e8805cc59"
        },
        {
          "id": "55f247c6d131446e8805cc5f",
          "name": "fnqr-daintree-understory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247c6d131446e8805cc5f"
        },
        {
          "id": "55f247c8d131446e8805cc65",
          "name": "fnqr-daintree-understory-oblique-C01-F02",
          "uri": "/api/v3/timestream/by-id/55f247c8d131446e8805cc65"
        }
      ],
      "uri": "/api/v3/experiment/by-id/55f249c4d131446fcca19a9c",
      "view": "/experiments/by-id/55f249c4d131446fcca19a9c"
    },
    {
      "access": 0,
      "description": "Description",
      "end_datetime": "2015-09-11T03:17:00",
      "expt_id": "FNQR-Robson",
      "id": "55f249f8d131446fcba19ad8",
      "is_supersite": true,
      "location_string": "Robson Creek",
      "name": "FNQR-Robson",
      "ongoing": false,
      "owner": {
        "id": null,
        "name": null
      },
      "spp": "Varied",
      "start_datetime": "2015-09-11T03:17:00",
      "timestreams": [
        {
          "id": "55f247ccd131446e8805cc75",
          "name": "fnqr-robson-overstory-nadir-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247ccd131446e8805cc75"
        },
        {
          "id": "55f247cdd131446e8805cc7b",
          "name": "fnqr-robson-overstory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247cdd131446e8805cc7b"
        },
        {
          "id": "55f247cdd131446e8805cc7c",
          "name": "fnqr-robson-understory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247cdd131446e8805cc7c"
        },
        {
          "id": "55f247ced131446e8805cc80",
          "name": "fnqr-robson-understory-oblique-C01-F02",
          "uri": "/api/v3/timestream/by-id/55f247ced131446e8805cc80"
        }
      ],
      "uri": "/api/v3/experiment/by-id/55f249f8d131446fcba19ad8",
      "view": "/experiments/by-id/55f249f8d131446fcba19ad8"
    }
  ]
}

Modify or Retrieve one resource§

endpoints
  • /api/v3/<resource type>/by-id/<resource id>
methods
  • GET
  • PATCH
  • DELETE
GET error codes
  • 200: OK
  • 404: Resource not found, or invalid authentication for resource.
PATCH error codes
  • 200: OK
  • 401: no authorisation for this resource
  • 405: no edit form for this resource type
  • 404: resource with provided id cannot be found
  • 400: invalid/missing data was/wasn’t provided and is required
  • 409: provided field is not unique and the spec requires uniqueness
  • 500: unknown error
DELETE error codes
  • 200: OK
  • 401: no authorisation for this resource
  • 404: resource with provided id cannot be found
  • 500: unknown error
Instance Example Response§
{
  "access": 0,
  "description": "Description",
  "end_datetime": "2015-09-11T03:17:00",
  "expt_id": "FNQR-Robson",
  "id": "55f249f8d131446fcba19ad8",
  "is_supersite": true,
  "location_string": "Robson Creek",
  "name": "FNQR-Robson",
  "ongoing": false,
  "owner": {
    "id": null,
    "name": null
  },
  "spp": "Varied",
  "start_datetime": "2015-09-11T03:17:00",
  "timestreams": [
    {
      "id": "55f247ccd131446e8805cc75",
      "name": "fnqr-robson-overstory-nadir-C01-F01",
      "uri": "/api/v3/timestream/by-id/55f247ccd131446e8805cc75"
    },
    {
      "id": "55f247cdd131446e8805cc7b",
      "name": "fnqr-robson-overstory-oblique-C01-F01",
      "uri": "/api/v3/timestream/by-id/55f247cdd131446e8805cc7b"
    },
    {
      "id": "55f247cdd131446e8805cc7c",
      "name": "fnqr-robson-understory-oblique-C01-F01",
      "uri": "/api/v3/timestream/by-id/55f247cdd131446e8805cc7c"
    },
    {
      "id": "55f247ced131446e8805cc80",
      "name": "fnqr-robson-understory-oblique-C01-F02",
      "uri": "/api/v3/timestream/by-id/55f247ced131446e8805cc80"
    }
  ],
  "uri": "/api/v3/experiment/by-id/55f249f8d131446fcba19ad8",
  "view": "/experiments/by-id/55f249f8d131446fcba19ad8"
}

Search Resources§

endpoints
  • /api/v3/search/<resource type>/<full text search query>
  • /api/v3/search/<resource type>?q=<full text search query>
methods
  • GET
GET error codes
  • 200: OK
  • 400: No query provided or query less than 3 characters
  • 404: Resource not found, or invalid authentication for resource
Search Example response§
{
  "_count": 2,
  "_cursor": 0,
  "_next": "/api/v3/search/experiment?q=FNQR&count=2&cursor=2",
  "_next_cursor": 2,
  "_total_count": 4,
  "resources": [
    {
      "access": 0,
      "description": "Description",
      "end_datetime": "2015-09-11T03:17:00",
      "expt_id": "FNQR-DDC",
      "id": "55f249c4d131446fcca19a9c",
      "is_supersite": true,
      "location_string": "Daintree Discovery Centre",
      "name": "FNQR-Daintree",
      "ongoing": false,
      "owner": {
        "id": "5587bd8cd1314423b7aac947",
        "name": "Gareth Dunstone"
      },
      "spp": "Varied",
      "start_datetime": "2015-09-11T03:17:00",
      "timestreams": [
        {
          "id": "55f247c4d131446e8805cc58",
          "name": "fnqr-daintree-overstory-nadir-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247c4d131446e8805cc58"
        },
        {
          "id": "55f247c4d131446e8805cc59",
          "name": "fnqr-daintree-overstory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247c4d131446e8805cc59"
        },
        {
          "id": "55f247c6d131446e8805cc5f",
          "name": "fnqr-daintree-understory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247c6d131446e8805cc5f"
        },
        {
          "id": "55f247c8d131446e8805cc65",
          "name": "fnqr-daintree-understory-oblique-C01-F02",
          "uri": "/api/v3/timestream/by-id/55f247c8d131446e8805cc65"
        }
      ],
      "uri": "/api/v3/experiment/by-id/55f249c4d131446fcca19a9c",
      "view": "/experiments/by-id/55f249c4d131446fcca19a9c"
    },
    {
      "access": 0,
      "description": "Description",
      "end_datetime": "2015-09-11T03:17:00",
      "expt_id": "FNQR-Robson",
      "id": "55f249f8d131446fcba19ad8",
      "is_supersite": true,
      "location_string": "Robson Creek",
      "name": "FNQR-Robson",
      "ongoing": false,
      "owner": {
        "id": null,
        "name": null
      },
      "spp": "Varied",
      "start_datetime": "2015-09-11T03:17:00",
      "timestreams": [
        {
          "id": "55f247ccd131446e8805cc75",
          "name": "fnqr-robson-overstory-nadir-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247ccd131446e8805cc75"
        },
        {
          "id": "55f247cdd131446e8805cc7b",
          "name": "fnqr-robson-overstory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247cdd131446e8805cc7b"
        },
        {
          "id": "55f247cdd131446e8805cc7c",
          "name": "fnqr-robson-understory-oblique-C01-F01",
          "uri": "/api/v3/timestream/by-id/55f247cdd131446e8805cc7c"
        },
        {
          "id": "55f247ced131446e8805cc80",
          "name": "fnqr-robson-understory-oblique-C01-F02",
          "uri": "/api/v3/timestream/by-id/55f247ced131446e8805cc80"
        }
      ],
      "uri": "/api/v3/experiment/by-id/55f249f8d131446fcba19ad8",
      "view": "/experiments/by-id/55f249f8d131446fcba19ad8"
    }
  ]
}