Introduction
EOSC Resource Catalogue is the heart of the EOSC Future ecosystem. It provides both data and functionality to register, maintain, administer and share resources onboarded by various providers. Moreover, it’s the point of reference for all EOSC Future components that provide added value to this information and help in making all this data and services searchable and accessible using various tools, both for researchers and end users.
The EOSC Resource Catalog is the result of merging the EOSC Service Catalogue (including data source services) and the EOSC Research Product Catalogue, together with the related list of EOSC providers. These are populated independently, as the resource onboarding process they support differs due to the different nature of the resources they manage, but their resources are interrelated. They can acquire metadata records from similar catalogues located within RI/clusters/other organizations premises or, in the case of research products, directly from the data sources. As a result, the EOSC Resource catalogue contains metadata about services, data sources, and research products, together with semantic relationships between them, highlighting the nature of the connection between services and products (e.g. hosted By, generated By, etc.)
This document describes the interoperability guidelines for using the API functionality of the EOSC Service Catalogue, an integral part of the EOSC Resource Catalogue hosting third-party catalogue Resources and Services (as already mentioned, the other part of the EOSC Resource Catalogue, the one that hosts Research Products is the EOSC Research Products Catalogue/Graph).
Onboarding and Managing a third-party catalogue to the EOSC Resource Catalogue
A high level overview of the workflow of onboarding an external EOSC catalogue is as follows:
1. Registration of the new Service Catalogue.
The catalogue admin provides details of the external EOSC catalogue, the records that will be onboarded onto the EOSC Resource Catalogue and declares conformance with the Onboarding Agreement. The catalogue will be inactive until EPOT approval. No authorization is required for this step. The API call used for this procedure is:
POST /catalogue
This API call requires as an input the data of the catalogue in json or xml format.
Parameters
Name | Value | Description | Required |
catalogue | json/xml format file with catalogue data | catalogue | Yes |
HTTP Valid Response Codes: 201 (Created), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
2. Onboarding providers
Next step is the verification of the catalogue content (or subset of it which will be onboarded), along with the other details contained within the Onboarding Agreement. This step is being conducted by EPOT team. The catalogue cannot be populated until approval by EPOT team.
When EPOT approves the catalogue onboarding request, then the third party catalogue owner should onboard their Resource Providers list. Importing of providers of each catalogue is possible using the following API call. The Catalogue admin/manager must provider the data of each provider and the catalogue id, in which the provider belongs.
POST /catalogue/{catalogueId}/provider
Parameters
Name | Value | Description | Required |
provider | json/xml format file with provider data | New provider | Yes |
catalogueId | text | Id of the catalogue | Yes |
HTTP Valid Response Codes: 201 (Created), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
3. Onboarding Resources
After the catalogue is being approved by EPOT, the catalogue admin can proceed with importing the resources.
The Catalogue admin/manager must provider the data of each resource and the catalogue id, in which the provider belongs.
POST /catalogue/{catalogueId}/resource
Parameters
Name | Value | Description | Required |
service | json/xml format file with resource data | New resource | Yes |
catalogueId | text | Id of the catalogue | Yes |
HTTP Valid Response Codes: 201 (Created), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
4.Updating of the records onto the production EOSC Resource Catalogue.
Once the catalogue is populated, authorized user (catalogue admin / EPOT) canupdate the catalogue data, using the following API calls.
Updating Catalogue registration data
PUT/catalogue
The authorized user provides the data of the catalogue to be updated. If wanted a comment can be also submitted (reason for update).
Parameters
Name | Value | Description | Required |
catalogue | json/xml format file with catalogue data | catalogue | Yes |
comment | text | Comment-reason for update | No |
HTTP Valid Response Codes: 201 (Created), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
Updating a Catalogue provider
PUT /catalogue/{catalogueId}/provider
The authorized user provides the data of the provider to be updated. If wanted a comment can be also submitted (reason for update).
Parameters
Name | Value | Description | Required |
provider | json/xml format file with provider data | provider | Yes |
catalogueId | text | Id of the catalogue on which the provider is registered | Yes |
Comment | text | Comment-reason for update | No |
HTTP Valid Response Codes: 201 (Created), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
Updating a Catalogue resource
PUT /catalogue/{catalogueId}/resource
The authorized user provides the data of the resource to be updated. If wanted a comment can be also submitted (reason for update).
Parameters
Name | Value | Description | Required |
service | json/xml format file with provider data | resource | Yes |
catalogueId | text | Id of the catalogue on which the provider is registered | Yes |
Comment | text | Comment-reason for update | No |
HTTP Valid Response Codes: 201 (Created), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
5. Deleting an entire Catalogue
There is the possibility to delete an onboarded the catalogue. The authorized user provides the id of the catalogue to be deleted.
This API call requires catalogue (provider) Admin or EPOT authorization.
DELETE /catalogue/delete/{id}
Parameters
Name | Value | Description | Required |
id | text | Catalogue id | Yes |
HTTP Valid Response Codes: 200 (OK), 204 (No Content), 403 (Forbidden), 404 (Not Found)
6. Deleting a Catalogue Provider
Authorized users (Admin or EPOT), can also delete catalogue providers.
The authorized user provides the id of the provider to be deleted. The id of the catalogue in which the provider belongs must also be provided.
DELETE/catalogue/{catalogueId}/provider/{id}
Parameters
Name | Value | Description | Required |
catalogueId | text | Catalogue id | Yes |
id | text | Provider id | Yes |
HTTP Valid Response Codes: 200 (OK), 204 (No Content), 403 (Forbidden), 404 (Not Found)
7. Deleting a Catalogue Resource
Authorized users (Admin or EPOT), can also delete catalogue providers.
The authorized user provides the id of the resource to be deleted. The id of the catalogue in which the resource belongs must also be provided.
DELETE /catalogue/{catalogueId}/resource/{id}
Parameters
Name | Value | Description | Required |
catalogueId | text | Catalogue id | Yes |
id | text | resource id | Yes |
HTTP Valid Response Codes: 200 (OK), 204 (No Content), 403 (Forbidden), 404 (Not Found)
8. Get all third party Catalogues
This API call is available to be used by all users.
If no filter is being given as an input this API call returns ALL the available catalogues.
Depending on the filters, the retrieved list may include only some selections.
GET /catalogue/all
Parameters
Name | Value | Description | Required |
query | text | Keyword to refine the search | No |
from | number | Starting index in the result set | No |
quantity | number | Quantity to be fetched | No |
order | asc/desc | Ascending or descending order | No |
orderField | number | Order field | No |
HTTP Valid Response Codes: 200 (OK), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
9. Get a third party Catalogue data
This API call is available to be used by all users and returns only the catalogue with the given id.
GET /catalogue/{id}
Parameters
Name | Value | Description | Required |
catalogueId | text | Id of catalogue | Yes |
HTTP Valid Response Codes: 200 (OK), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
10. Get all Providers of a third party Catalogue
This this API call (which is available to be used by all users), returns ALL the providers of a given catalogue.
Depending on the filters, the retrieved list may include only some selections.
GET /catalogue/{catalogueId}/provider/all
Parameters
Name | Value | Description | Required |
catalogueId | text | Id of catalogue | Yes |
query | text | Keyword to refine the search | No |
from | number | Starting index in the result set | No |
quantity | number | Quantity to be fetched | No |
order | asc/desc | Ascending or descending order | No |
orderField | number | Order field | No |
HTTP Valid Response Codes: 200 (OK), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
11. Get a Provider of a third party Catalogue
This this API (which is available to be used by all users), call returns only the provider with the given in the parameters id, of a given catalogue.
GET /catalogue/{catalogueId}/provider/{providerId}
Parameters
Name | Value | Description | Required |
catalogueId | text | Id of catalogue | Yes |
providerId | text | Id of provider to be fetched | Yes |
HTTP Valid Response Codes: 200 (OK), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
12. Get all Resources of a third party Catalogue
This this API (which is available to be used by all users), call returns all the resources of a the provider with the given in the parameters id, of a given catalogue.
GET /catalogue/{catalogueId}/{providerId}/resource/all
Parameters
Name | Value | Description | Required |
catalogueId | text | Id of catalogue | Yes |
providerId | text | Id of provider of which the services to be fetched | Yes |
HTTP Valid Response Codes: 200 (OK), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)
13. Get a Resource of a third party Catalogue
This this API call, (which is available to be used by all users), returns only the resource with the given in the parameters id, of a given catalogue.
GET /catalogue/{catalogueId}/resource/{resourceId}
Parameters
Name | Value | Description | Required |
catalogueId | text | Id of catalogue | Yes |
resourceId | text | Id of resource to be fetched | Yes |
HTTP Valid Response Codes: 200 (OK), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found)