Accessing the service

The BioSamples API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication, HTTP verbs and content-negotiation.

Hypermedia

This API uses hypermedia, and resources include links to other resources in their responses. Responses are in HAL format. Links can be found beneath the _links key. API users should not build links themselves, but should use these links to navigate between resources. Clients should discover resources and available actions by consuming the _links.

Links may be returned in templated form, requiring expansion prior to use. This is primarily true for search resources. Templated links follow RFC6570.

Link naming follows a consistent pattern.

  • Each resource includes a self link. This is the canonical link to the resource, although there may be others

  • Individual resources are named with the type name, e.g. sample

  • Collection resources are named with the plural of the type name in camel case, e.g. samples, curations, curationLinks

For a reference of links available in BioSamples check the corresponding Links section

Content negotiation for data representation

BioSamples is able to serve data using different serializations and provides this functionality through content negotiation HTTP standard. Even if JSON format is the recommended format for API interactions, in BioSamples’s supported serializations table you can find a list of all the currently available data representations in BioSamples

Table 1. BioSamples’s supported serializations table
Type Header Comments

HTML

Accept: text/html

JSON

Accept: application/hal+json or Accept: application/json

Recommended

JSON-LD

Accept: application/ld+json

Use to serve BioSchemas content

XML

Accept: text/xml or Accept: application/xml

Soon deprecated

HTTP conventions

Authentication

In BioSamples, user authentication and authorization functionalities are supported by the mean of a JWT token provided in the HTTP request header. For more information on how authentication works in BioSamples, check the authentication guide.

All our API examples that require a JWT token to be fullfilled, will use $TOKEN as a placeholder instead.

Supported HTTP verbs

The BioSamples API aims to use appropriate HTTP verbs for each action. Not all the verbs are available in the BioSamples API, and you can check the supported one in the BioSamples’s API supported verbs table

Table 2. BioSamples’s API supported verbs table
Verb Description

GET

Used for retrieving resources

POST

Used for creating resources

PUT

Used to entirely replace resources

OPTIONS

Can be used to determine which verbs can be used for a resource

HEAD

Returns whether a resource is available

PATCH

Used to add structured data (e.g. Antobiogram data) to already existing samples

HTTP Status codes

BioSamples uses standard response status code to show the outcome of each HTTP request. You can find a complete reference on HTTP status codes on MDN web docs

Status code Description

200 OK

The request completed successfully

201 Created

Returned after successfully creating a new resource with a POST request

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The request did not include an Authorization header

403 Forbidden

You are not permitted to access this resource

405 Method Not Allowed

The request used a method that is not permitted

HTTPS vs HTTP

BioSamples content is by default served using the HTTPS protocol. The adoption of HTTPs follows an EMBL-EBI guidelines. You can find some more details about these guidelines in this Technical Services Cluster blog post