Skip to content
×

General approach

The API is based on HTTP GET and POST requests only. POST requests are used for any kind of resource creation, mutation, or deletion. GET requests are read-only and idempotent.

GET

GET end-points provide access to REST-style resources such as:

GET /api/public/v1/dataset/821

POST

POST end-points have an optional prefix indicating a REST-style resource to be operated on, and a verb phrase suffix indicating the desired operation:

POST /api/public/v1/dataset/821/analyze

JSON

Requests and responses use JSON bodies, except for file upload and download. Text-based requests and responses use UTF-8 encoding.

JSON responses are uniformly packaged in success/error envelopes, the binary status conveniently indicated by a status field with value success or error.

Successful responses have an optional payload field which is a nested JSON object with response details:

{ payload: object, status: "success" }

Errors

Error responses have code and message fields. The code is for programmatic handlers and is considered part of the API. The message is for humans to read and the exact content is not considered part of the API surface that clients should depend upon.

{ code: string, message: string, status: "error" }

Because of the success/error envelopes, JSON responses use HTTP status code 200 OK for both success and error responses. HTTP 4xx or 5xx error codes are returned only in a few, generic error cases, listed below. In each of these cases, the response body is deemed irrelevant, meaning it is not part of the API surface that clients should depend upon.

  • 403 Forbidden when authorization fails.
  • 404 Not Found when attempting to access an undefined end-point.
  • 500 Internal Server Error when code execution on the server fails. This may indicate a programming error on our side, and we welcome bug reports at support@jadbio.com.


Note of appreciation to JADBio users

We constantly make changes in the software and do our best to update these materials, but you may notice some differences. We welcome your feedback on how to make this more useful for you and requests for future tutorials.