API Overview
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
Type | Header | Comments |
---|---|---|
HTML |
|
|
JSON |
|
Recommended |
JSON-LD |
|
Use to serve BioSchemas content |
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
Verb | Description |
---|---|
|
Used for retrieving resources |
|
Used for creating resources |
|
Used to entirely replace resources |
|
Can be used to determine which verbs can be used for a resource |
|
Returns whether a resource is available |
|
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 |
---|---|
|
The request completed successfully |
|
Returned after successfully creating a new resource with a |
|
The request was malformed. The response body will include an error providing further information |
|
The request did not include an |
|
You are not permitted to access this resource |
|
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