API reference - basics

Authentication

An authentication token is required to access most API endpoints. To get a token, make a request to the token_auth endpoint (URL), specifying your CoralNet username and password. You can then specify that token in a subsequent request's HTTP headers to authenticate as that CoralNet user.

curl example of specifying a token in an HTTP header:

curl -v -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" https://coralnet.ucsd.edu/api/deploy_job/7/status/

In this case the token itself is f22f560a2186c0380962fc9b6da9b365102ef984.

Content types

POST requests to the API must have a Content-type: application/vnd.api+json header.

API responses will also use the application/vnd.api+json content type. In general, your client program will probably accept this content type if you don't bother adding any specific Accept header. However, if you suspect any issues here, try adding application/vnd.api+json to your request's Accept header.

The API may incidentally support other content types for some endpoints, but in general application/vnd.api+json is the only input and output format that is officially supported.

Rate limits

Each user is allowed to make up to a certain amount of requests per minute and per hour. Also, each user is limited to a certain number of concurrent deploy jobs.

If rate limits are exceeded, the server will respond with a '429 Too Many Requests' status. If this happens, you have to wait some time before making further requests.

We try to set the rate limits to strike a balance between server load and what users need to get their work done. The API is still in early-adoption stages, and we don't have a great sense of what the best balance is yet. So feel free to make your case if you think we've set the rates too conservatively.

Request and response formats

Formats are loosely based on jsonapi.org, but are not always guaranteed to match that specification. We may sometimes deviate intentionally from jsonapi.org for convenience's sake.

API reference - endpoints (URLs)

When an endpoint is listed as

/api/token_auth/

that means the full URL you need to access is

https://coralnet.ucsd.edu/api/token_auth/

Be sure to include the trailing slash.

If a URL contains :id, you should replace :id with the ID number of a CoralNet resource. The resource type is indicated by the preceding noun. For example, in /api/classifier/:id/deploy/, you should replace :id with a classifier ID.

/api/token_auth/ - POST

Obtain an authentication token for a particular CoralNet user account. You can then specify that token in a subsequent request's HTTP headers to authenticate as that CoralNet user.

Permissions required: None. Also, this is the only endpoint which does not require an auth token to use.

Request fields

username (string): Username of the CoralNet user account.
password (string): Password of the CoralNet user account. For security, be sure that you are sending your request to an https:// URL, not http://. This goes for all API endpoints, but especially this one.

Example request with curl:

curl -H "Content-type: application/vnd.api+json" -d '{"username": "stephen", "password": "my_password"}' https://coralnet.ucsd.edu/api/token_auth/

Response

200 OK on success, with the following JSON fields:

token (string): The authentication token. This can be used for authentication in subsequent requests to the API, using an Authorization header. For example: Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984

Example response:

{"token":"f22f560a2186c0380962fc9b6da9b365102ef984"}

/api/classifier/:id/deploy/ - POST

Deploys the classifier of ID :id on new images.

Permissions required: View permission on the source that the classifier belongs to. (This means the source is public, or you are a member of the source.)

Request fields

An array of jsonapi.org resources of type 'image', each with the following attributes:

url (string): Public URL to an image.
points (array of hashes): One hash per annotation point, with each hash containing:
- row (integer): Pixel row in the image, starting from 0 at the top.
- column (integer): Pixel column in the image, starting from 0 at the left.

Limits: 100 images per request, 200 points per image. (We will support 1000 points per image in the near future.)

Example request with curl:

curl -v -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" -H "Content-type: application/vnd.api+json" -d '{"data": [{"type": "image", "attributes": {"url": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg", "points": [{"row":700,"column":500}, {"row":1100,"column":900}]}}]}' https://coralnet.ucsd.edu/api/classifier/5/deploy/

Here is the POST data in an easier-to-read format:

{
  "data": [
    {
      "type": "image",
      "attributes": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg",
        "points": [
          {
            "row": 700,
            "column": 500
          },
          {
            "row": 1100,
            "column": 900
          }
        ]
      }
    }
  ]
}

Response

202 Accepted on success, with no body content. The Location header contains a URL where the status of this classifier deployment job can be checked.

/api/deploy_job/:id/status/ - GET

Gives status information on the classifier deployment job of ID :id.

Permissions required: Must be the user who initiated this deployment job.

Request fields

None.

Example request with curl:

curl -v -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" https://coralnet.ucsd.edu/api/deploy_job/7/status/

Response

200 OK if deployment is not finished. Response contains an array of jsonapi.org resources of type 'job', each with the following attributes:

status (string): Pending or In Progress.
successes (integer): Number of images that have been classified successfully so far.
failures (integer): Number of images that CoralNet attempted to classify, but encountered an error when doing so.
total (integer): Total number of images in the requested deployment, including images that haven't been processed yet.

303 See Other if deployment is finished, with no body content. The Location header contains a URL where the result of this classifier deployment job can be obtained.

Example 200 OK response:

{
  "data": [
    {
      "type": "job",
      "id": "7",
      "attributes": {
        "successes": 0,
        "failures": 1,
        "total": 2,
        "status": "In Progress"
      }
    }
  ]
}

/api/deploy_job/:id/result/ - GET

Gives the result of the finished classifier deployment job of ID :id. Each result expires 30 days after the deployment job has finished.

Permissions required: Must be the user who initiated this deployment job.

Request fields

None.

Example request with curl:

curl -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" https://coralnet.ucsd.edu/api/deploy_job/7/result/

Response

200 OK, containing an array of jsonapi.org resources of type 'image', each with the following attributes:

url (string): Same as the deploy request.
points (array of hashes): Present if the image was classified successfully. One hash per annotation point, with each hash containing:
- row (integer): Same as the deploy request.
- column (integer): Same as the deploy request.
- classifications (array of hashes): The top suggestions for each point, with up to 5 suggestions, from 1st (best) to 5th (worst). One hash per suggestion. Each hash contains:
  - label_id (string): CoralNet label ID for the suggested label.
  - label_name (string): Full name of the suggested label.
  - label_code (string): Short code of the suggested label. This is the custom short code specified by the classifier's source, not the label's default code.
  - score (float): Score between 0 and 1 indicating how confident the classifier is regarding its label suggestion. 0 indicates 0% confidence, and 1 indicates 100% confidence.
errors (array of strings): Present if the image failed to be classified. Each array element is an error message.

Example response:

{
  "data": [
    {
      "type": "image",
      "id": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg",
      "attributes": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg",
        "points": [
          {
            "row": 700,
            "column": 500,
            "classifications": [
              {
                "label_id": 2093,
                "score": 0.8926345481464616,
                "label_code": "*CORAL",
                "label_name": "CREP-T1 Coral"
              },
              {
                "label_id": 2097,
                "score": 0.03736297079656042,
                "label_code": "*CCA",
                "label_name": "CREP-T1 Crustose coralline algae"
              },
              {
                "label_id": 2096,
                "score": 0.024002975584768303,
                "label_code": "*MA",
                "label_name": "CREP-T1 Macroalgae"
              },
              {
                "label_id": 2098,
                "score": 0.02297470070442297,
                "label_code": "*SED",
                "label_name": "CREP-T1 Sediment"
              },
              {
                "label_id": 2099,
                "score": 0.019182308307261246,
                "label_code": "*TURF",
                "label_name": "CREP-T1 Turf algae"
              }
            ]
          }
        ]
      }
    },
    {
      "type": "image",
      "id": "https://commons.wikimedia.org/wiki/File:Porites_porites_French_Bay.jpg",
      "attributes": {
        "url": "https://commons.wikimedia.org/wiki/File:Porites_porites_French_Bay.jpg",
        "errors": [
          "Could not download this image."
        ]
      }
    }
  ]
}