The REST API allows you to retrieve, update, or remove asset metadata in the metadata catalogue. The assets are indexed from many different platforms, such as educational resources from AIDA, datasets from HuggingFace, models from OpenML, and many more.
The REST API is available at https://api.aiod.eu and documentation on endpoints is available on complementary Swagger and ReDoc pages.
To use the REST API, simply make HTTP requests to the different endpoints.
Generally, these are GET requests when retrieving data, PUT requests when modifying data, POST requests when adding data, and DEL requests when deleting data. The video and text below show examples on how to use the REST API.
Here are some examples on how to list datasets in different environments:
=== "Python (requests)"
This example uses the [`requests`](https://requests.readthedocs.io/en/latest/) library to list datasets.
``` python
import requests
response = requests.get("https://api.aiod.eu/datasets/v1?schema=aiod&offset=0&limit=10")
print(response.json())
```
=== "CLI (curl)"
This example uses [curl](https://curl.se/) to retrieve data from the command line.
``` commandline
curl -X 'GET' \
'https://api.aiod.eu/datasets/v1?schema=aiod&offset=0&limit=10' \
-H 'accept: application/json'
```
Additionally, we also provide an aiondemand package for Python
to simplify access to the REST API. You can see an example of that below, and we refer to their dedicated
documentation pages for full installation and usage instructions.
import aiod
aiod.datasets.get_list()Earlier versions of the metadata schema included a contact_details
field on the Person and Organisation entities which represented
a one-to-one relationship with a contact.
This field is now deprecated and has been removed from the data model.
Instead, contacts should be defined using the generic contact mapping
available at the AIResource level. This mapping allows multiple
contacts to be associated with a resource using a list of contact
identifiers.
Recommended approach
Use the contacts list defined on the AIResource level.
level rather than defining contacts directly on Person or
Organisation.
Compatibility
This change is treated as non-breaking. Existing one-to-one
contact_details mappings are migrated automatically to the
many-to-many contact link table during database migrations.
By navigating to the Swagger documentation, you can find information and examples on how to access the different endpoints.
For example, if we navigate to the GET /datasets/v1
endpoint and expand the documentation by clicking on the down chevron (v), we can see the different query parameters
and can execute a call directly on the API:
Click the Try it out button to be able to modify the parameter values and then click the execute button to make the request directly from the documentation page.
Under response you will also see an example on how to make the request through the command line using curl, e.g.:
curl -X 'GET' \
'https://api.aiod.eu/datasets/v1?schema=aiod&offset=0&limit=10' \
-H 'accept: application/json'Below the example, you will find a section Server Response which displays the actual response from the service (if you clicked execute).
Normally, this should look similar to the image below; a HTTP Status Code,
and data (in JSON).
Below the actual server response is a response section which lists information about the possible responses, including
for example different error codes.
!!! tip
When exploring these endpoints, prefer to connect to the test server instead to avoid editing production data.
You can find the test API at [https://aiod-dev.i3a.es](https://aiod-dev.i3a.es).
The POST and PUT endpoints allow the addition or modification of assets on the platform.
You can explore them in a similar way as with the GET endpoints, with two important differences.
The first is that they require authentication.
To authenticate within the Swagger pages, navigate to the top and click Authorize and log in.
Scroll up to OpenIdConnect (OAuth2, authorization_code with PKCE) and click Authorize to be taken to
the keycloak login page. Log in with your preferred identity provider through EGI Check-in.
The second important distinction as that you will provide data through a JSON body instead of individual parameters.
The documentation page will prepopulate example data to help you know what information to provide under
the Example Value tab of the Request Body section. To know what values are accepted, you can click the
Schema tab instead.
The ReDoc documentation provides pretty similar functionality to the Swagger documentation. The main difference is that the Swagger page allows you to run queries against the REST API, whereas the ReDoc documentation does not. However, some people prefer the organisation of ReDoc, especially with respect to documentation of the expected responses and the schema documentation.
The Swagger documentation gives examples on how to use CURL for the various endpoints.
To see examples, simply expand the endpoint's documentation and click Try it out, fill in any parameters, and click Execute.
The query will be executed, but it will also generate a curl command which matches the query.
For example, listing the first 10 datasets:
curl -X 'GET' \
'http://api.aiod.eu/datasets/v1?schema=aiod&offset=0&limit=10' \
-H 'accept: application/json'