EOSC Portal Application Programming Interface Tutorial

1. EOSC Portal Application Programming Interface Tutorial
v1.00 – 30/09/2020
Dr. George Papastefanatos, Stefania Martziou, Antonis Lempesis, NKUA, Dr. Jorge Sanchez, JNP

2. Overview of the EOSC Portal API

3. Introduction
The EOSC Portal API [1] is a lightweight web service with a REST interface which
provides easy access to the EOSC Portal Registry.
The complete EOSC Portal API documentation is, a living document, generated using
frameworks compliant with OpenAPI Specification, available at https://api.eosc-
portal.eu
For any queries or difficulties using the EOSC Portal API please contact us at
api@eosc-portal.eu
[1] An Application Programming Interface (API) is a protocol intended to be used as an interface by
software components to communicate with each other.

4. Steps to activate the EOSC Portal API
To activate the EOSC Portal API, three steps should be implemented in sequence:
1.The ARP [1] onboards the Provider and one Resource at the EOSC Portal Web
Interface.
2.The ARP obtains an EOSC Portal API token to be used for authorization.
3.The Provider organization uses the API methods [2] to create, update or retrieve
content from the EOSC Portal.
[1] ARP: Authorized Representative of a Provider
[2] Details of the methods at https://api.eosc-portal.eu

5. 1. Onboarding to the EOSC Portal

6. Onboarding to the EOSC Portal
To be able to use the EOSC Portal API the ARP needs first to Onboard the Provider and
one Resource and be approved by the EPOT [1].
The ARP needs to follow the Onboarding Process detailed in the “EOSC Portal Provider
and Resource Onboarding Process Tutorial” and to structure the information following
the “EOSC Portal Provider and Resource Profiles Tutorial”.
In short, the steps to be followed are:
An ARP registers him/herself into the EOSC Portal via the EOSC Authentication and Authorization Infrastructure (AAI).
The AARP [2] onboards the Provider using the ESOC Provider Profile and receives approval by the EPOT.
The AARP onboards the first Resource offered by the Provider using the ESOC Resource Profile and receives approval by the EPOT.
After this, the onboarding is complete, and the AARP may proceed to the next steps of the activation of the EOSC Portal API.
[1] EPOT = EOSC Portal Onboarding Team
[2] AARP: Authorised and Authenticated Representative of a Provider (AARP)

7. Onboarding to the EOSC Portal
This step is a prerequisite for the EOSC Portal API activation,
since it accommodates qualified population of the EOSC Portal.
The EOSC Provider and Resource Profiles are validated by the EPOT. If
issues are identified, the EPOT contacts the ARP, so that these are
rectified.
The ARP gets familiarized with the EOSC Portal Profiles (data models)
and is able to properly use the EOSC Portal API methods for inserting
and updating content.
This step is performed only once; upon completion, the EOSC
Provider is onboarded at the EOSC Portal and the AARP can
seamlessly use the EOSC Portal API as described in the next
sections.

8. 2. Obtaining an EOSC Portal API token

9. Obtaining an EOSC Portal API token
The ARP obtains an API token by signing into the
AAI service of the EOSC Portal [1].
This token is not persistent. It is valid for 8 hours; after its
expiration the ARP will have to obtain a new one.
The token is used in the Authorization header
when making requests to the EOSC Portal.
The token is not required when retrieving information
using the GET methods.
To use the token directly in the API page, the ARP needs
to click 'Authorize' and fill in the ‘api_key’ field with the
token obtained.
[1] https://aai.eosc-portal.eu/eic-api/token.php

10. 3. Using the API methods

11. Using the API methods
Having obtained the API token, the AARP is
able to use the EOSC Portal API methods:
GET methods: to retrieve information from the EOSC
Portal.
POST methods: to create and validate a new Resource at
the EOSC Portal.
PUT methods: to update information at the EOSC Portal.
The available methods are organized in
Provider and Resource-specific controllers [1].
[1] https://api.eosc-portal.eu

12. Using the API methods
To insert or update Resources at the EOSC
Portal, these Resources need to be
represented in JSON format, adhering to the
EOSC Portal Profiles
EOSC Portal Profiles are currently in v3.00.
Examples of Resources represented in JSON format
and adhering to the EOSC Portal Profiles are
provided by expanding each API method [1].
Example EOSC Portal API calls for several API
methods are provided in the next sections.
[1] https://api.eosc-portal.eu

13. EOSC Portal API – GET Examples
GET Provider: Returns the EOSC Provider Profile with the given Provider id
GET /api/provider/{providerId}
GET Resource: Returns the most current version of the Profile of a Resource, providing the Resource id
GET /api/resource/{resourceId}
GET All Resources: Returns a list of all onboarded Resources at the EOSC Portal
GET /api/Resource/all

14. EOSC Portal API – POST Examples
Add Resource: Creates a new Resource in the
EOSC Portal Registry
POST /api/resource
{
"name": "Example Resource",
"resourceOrganisation": "example",
"resourceProviders": [null],
"webpage": "https://example.com",
"description": "Example Resource Description",
"tagline": "Example",
"logo": "https://example.com/logos/example2.png",
"multimedia": ["https://example.com/multimedia"],
"useCases": ["https://example.com/use_case"],
"scientificSubdomains": ["scientific_subdomain-other-other"],
Add Resource (continued)
"subcategories": ["subcategory-other-other-other"],
"targetUsers": ["target_user-other" ],
"accessTypes": ["access_type-other" ],
"accessModes": ["access_mode-other" ],
"tags": ["Example Tag" ],
"geographicalAvailabilities": ["EL"],
"languageAvailabilities": ["en" ],
"resourceGeographicLocations": ["EL" ],
"mainContact": {"firstName": "string",
"lastName": "string",
"email": "string",
"phone": "string",
"position": "string",
"organisation": "example"},

15. Add Resource (continued)
"publicContacts": [
{"firstName": "string",
"lastName": "string",
"email": "string",
"phone": "string",
"position": "string",
"organisation": "example"}
],
"helpdeskEmail": "string",
"securityContactEmail": "string",
"trl": "trl-1",
"lifeCycleStatus": "life_cycle_status-other",
"certifications": ["string"],
Add Resource (continued)
"standards": ["string"],
"openSourceTechnologies": ["string"],
"version": "string",
"lastUpdate": "2020-01-01",
"changeLog": ["string"],
"requiredResources": [ null ],
"relatedResources": [ null ],
"relatedPlatforms": [ null ],
"fundingBody": ["funding_body-other" ],
"fundingPrograms": [ "funding_program-other" ],
"grantProjectNames": ["string" ],
"helpdeskPage": "https://example.com",
"userManual": "https://example.com",
EOSC Portal API – POST Examples

16. Add Resource (continued)
"termsOfUse": "https://example.com",
"privacyPolicy": "https://example.com",
"accessPolicy": "https://example.com",
"serviceLevel": "https://example.com",
"trainingInformation": "https://example.com",
"statusMonitoring": "https://example.com",
"maintenance": "https://example.com",
"orderType": "order_type-other",
"order": "https://example.com",
"paymentModel": "https://example.com",
"pricing": "https://example.com"
}
EOSC Portal API – POST Examples

17. Update Provider: Updates the EOSC
Provider assigned the given id with the
given Provider, keeping a version of
revisions
PUT /api/provider
{ "id": "provider_id",
"name": "Example Provider",
"abbreviation": "example",
"website": "https://example.com",
"legalEntity": true,
"legalStatus": "provider_legal_status-other",
"description": "Example Description",
"logo": "https://example.com/logos/logo.png",
"multimedia": ["https://example.com/multimedia" ],
Update Provider (continued)
"scientificSubdomains": ["scientific_subdomain-other-
other"],
"tags": ["Example Tag"],
"location": {"streetNameAndNumber": "Street, 0",
"postalCode": "0",
"city": "City",
"region": "Region",
"country": "EL"},
"mainContact": {"firstName": "Name",
"lastName": "Surname",
"email": "ex@example.com",
"phone": "00000000000000",
"position": "Example Position"},
EOSC Portal API – PUT Examples

18. Update Provider (continued)
"publicContacts": [
{"firstName": "Another Name",
"lastName": "Another Surname",
"email": "ex2@example.com",
"phone": "100000000000001",
"position": "Example Position 2"}
],
"lifeCycleStatus": "provider_life_cycle_status-other",
"certifications": ["Example Certification" ],
"hostingLegalEntity": "Example",
"participatingCountries": ["EL" ],
"affiliations": ["string"],
"networks": ["provider_network-other" ],
Update Provider (continued)
"structureTypes": ["provider_structure_type-other" ],
"esfriDomains": ["provider_esfri_domain-other" ],
"esfriType": "provider_esfri_type-other",
"merilScientificSubdomains": [
"provider_meril_scientific_subdomain-
information_science_and_technology-
software_service_facilities" ],
"areasOfActivity": ["provider_area_of_activity-other"],
"societalGrandChallenges": [
"provider_societal_grand_challenge-other"],
"nationalRoadmaps": ["string" ]
}
EOSC Portal API – PUT Examples

19. 11/11/2020 19
Disclaimer
The information contained in this document is provided by the copyright holders "as is" and any express or
implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a
particular purpose are disclaimed. In no event shall the authors or the European Commission be liable for
any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to,
procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however
caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or
otherwise) arising in any way out of the use of the information contained in this document, even if advised
of the possibility of such damage. The sole responsibility for the content of this publication lies with the
authors. It does not necessarily reflect the opinion of the European Commission. The European Commission
is not responsible for any use that may be made of the information contained therein.
Copyright
This work by JNP, NKUA and CYFRONET is licensed under a Creative Commons Attribution 4.0 International
License (http://creativecommons.org/licenses/by/4.0/).

20. https://www.eosc-portal.eu/
info@eosc-portal.eu
https://twitter.com/eoscportal

21. Q&A