REST API
Overview
The base URL is the URL of your Alyx installation, for example at IBL: https://openalyx.internationalbrainlab.org
With REST, you make an HTTP request to a particular URL, named an endpoint, with possibly some parameters, and you obtain a response in JSON. There are several types of HTTP requests used in Alyx:
- GET
obtain read-only data about an object, or perform a query
- POST
create a new object
- PATCH
update some fields of an object
- PUT
update all fields of an object
Some GET endpoints return a list of objects satisfying to your query, while other endpoints return the detail of a single object.
The / endpoint (base URL) returns the list of all available endpoints.
Every object is identified with a unique 128-bit UUID, representing by a string of 32 hexadecimal digits, like e.g. 6915b95b-c6d4-45a6-80c3-324675723d3e.
When we say to do a GET request to the /blah/ endpoint, we mean to perform an HTTP GET request to the url https://yourbaseurl/blah/.
With POST, PATCH, and PUT requests, data is passed as key-value pairs in JSON. For example, doing a POST request to the /blah/ endpoint with key1=val1 and key2=val2 means performing an HTTP POST request to the url https://yourbaseurl/blah/ with data a string with the application/json mime type, and the contents {“key1”: “val1”, “key2”: “val2”}.
In practice, a library in your language should provide you with primitives such as get(url), post(url, key1=val1, …), etc. so you don’t need to understand all of the underlying details: just the HTTP request type, the endpoint URL, the fields you need to pass, and the fields that are returned by the endpoint.
Going further
The list of endpoints, fields and methods is self-documented for each database at the /docs URL. For example, a public Alyx instance is available here for reference: https://openalyx.internationalbrainlab.org/docs/
REST endpoints are programmatically accessed client side. And example of a client side application is described in details here: https://int-brain-lab.github.io/ONE/.