Overview

Accessing the service

The BioSamples API is organized around REST. It provides predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. It leverages HTTP features such as authentication, verbs, and content negotiation.

Hypermedia

This API uses hypermedia—the responses include links to other resources. Responses follow the HAL format and contain _links, which clients should use to navigate between resources. Links may be templated (RFC 6570) and require expansion before use.

Link naming conventions:

Each resource includes a self link (the canonical URL).
Individual resources: named with singular type name (e.g., sample).
Collections: named with camelCased plurals (e.g., samples, curations, curationLinks).

Refer to the Links section for a list of all available API links.

Content negotiation for data representation

BioSamples supports multiple serialization formats via HTTP content negotiation. Although JSON is recommended for API interactions, other supported formats include:

BioSamples’s supported serializations
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 to be deprecated

HTTP conventions

Authentication

Authentication is managed via a JWT token in the HTTP request header. For more details see the authentication guide In examples requiring authorization, use $TOKEN as a placeholder.

Supported HTTP verbs

BioSamples API follows HTTP method conventions with HTTP verbs for each action. See below for the list of verbs available in the BioSamples API.

BioSamples’s API supported verbs
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. antibiogram data) to existing samples

HTTP Status codes

The API uses standard HTTP status codes to indicate request outcomes. For a full reference, see MDN Web Docs.

BioSamples’s API HTTP status codes
Code	Description
`200 OK`	The request completed successfully.
`201 Created`	Returned after a successful `POST` creating a new resource.
`400 Bad Request`	The request was malformed. The response body will include details about the issue.
`401 Unauthorized`	The request did not include an `Authorization` header or the credentials were invalid.
`403 Forbidden`	The client is not permitted to access this resource.
`405 Method Not Allowed`	The HTTP method is not allowed on this resource.

HTTPS vs HTTP

BioSamples is served exclusively over HTTPS in line with EMBL-EBI’s security guidelines. Refer to the linked Technical Services Cluster blog post for full details.