Introduction
You will find a detailed overview of the steps required when using the Interoperable Europe Portal’s Assessments API. Adherence to these guidelines ensures secure, reliable, and efficient integration.
Access Request
You can request access to Assessments API as registered users of the Interoperable Europe Portal (if you do not have a Portal account, check the Portal's User Reference Guide to view the instructions on creating one). Only European public administrations can request access.
The following steps need to be applied to request access:
1. Click on the user profile icon in the menu bar, and then click on My account.
2. On the My account page, click on the 3 dots menu, and then click on API client request.
3. On the API client request page, click on Request client.
4. On the request page, enter the mandatory information, marked by an asterisk, and click Save to submit the request.
5. If the request has been submitted successfully, you should see a success message.
6. Once the request for API access has been submitted successfully, the Portal moderators will receive a notification to approve the request. If the request is approved, you will receive an email notification.
Credentials Management
Before using the API for the first time, the client secret must be updated. Please follow the steps below for this.
1. On the My account page, click on the 3 dots menu, and then click on API clients.
2. On the API clients page, click on Edit for the client for which you want to manage access.
3. On the API clients page, insert the new client secret and click Save.
4. If the client secret is updated successfully, you will see a corresponding success message.
API Usage
Full technical details about the API can be found in the Swagger documentation. The following sections provide only a high-level description of the available API endpoints. Please refer to the Swagger documentation for more details.
The API uses OAuth based authentication, and there is a dedicated API endpoint which will provide the authentication token to be used in other endpoints.
Endpoint
POST /oauth/token
Request
The request body must contain the following parameters
| Parameter | Value | Comments |
|---|---|---|
| grant_type | client_credentials | static value |
| client_id | The OAuth2 client identifier as seen in your profile page's OAuth2 clients section | |
| client_secret | The OAuth2 client secret you set when your client is approved | |
| scope | assessments | static value |
Response
The response should contain an access_token, which must be used to access other endpoints of the API. Below you can see a sample response.
{
"token_type": "Bearer",
"expires_in": 299,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImR"
}
Error Scenarios
If any of the parameters is missing or has an invalid value, the API will return a corresponding error.
| Error Code | Error Scenario |
|---|---|
| 400 Bad Request | Insufficient details provided |
| 401 Unauthorised | Invalid access token provided |
This operation allows to submit a single Assessment JSON object. Some referred objects (such as provider or asset) can be either reused by passing their ID, or created by passing fully structured objects, as is defined by their schema.
Endpoint
POST /api/assessments/v1/assessment
Request
The request body must contain the full JSON object representing an assessment. Please refer to the schema section in the swagger document to check the structure of assessment JSON object.
Response
Upon successful submission, the API will return the identifier of the newly created assessment report, together with the full assessment object.
Error Scenarios
If the request is incomplete or fails validation checks, the API will return a corresponding error.
| Error Code | Error Scenario |
|---|---|
| 401 Unauthorised | Invalid access token provided |
| 403 Forbidden | Access token missing |
| 405 Method Not Allowed | Incorrect HTTP method provided |
| 422 Unprocessable Content | Mandatory attributes missing |
This operation returns all assessment reports dependently on country code of referenced public institution.
Endpoint
GET /api/assessments/v1/assessment
Request
Request may contain the following parameters
| Parameter | Description | Value |
|---|---|---|
| country | The two-letter ISO-3166 country code to filter reports by their provider's country. Alternatively, use "EU" to fetch reports from EU institutions, bodies, agencies. | One of AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE |
| page | Page number for pagination (0-indexed). Each page contains 200 items. Default is 0 (first page). | Any numeric value |
Response
Response contains the list of fetched reports.
Error Scenarios
If the request is incomplete or incorrect, the API will return a corresponding error.
| Error Code | Error Scenario |
|---|---|
| 401 Unauthorised | Invalid access token provided |
| 403 Forbidden | Access token missing |
| 405 Method Not Allowed | Incorrect HTTP method provided |
This operation returns a specific assessment report object.
Endpoint
GET /api/assessments/v1/assessment/{id}
Request
The request must contain the identifier of the assessment object being fetched.
Response
The response contains the fetched assessment object.
Error Scenarios
If the request is incomplete or incorrect, the API will return a corresponding error.
| Error Code | Error Scenario |
|---|---|
| 401 Unauthorised | Invalid access token provided |
| 403 Forbidden | Access token missing |
| 404 Not Found | No resource found matching the provided identifier |
| 405 Method Not Allowed | Incorrect HTTP method provided |
This operation returns all assets (also known as interoperability solutions).
Endpoint
GET /api/assessments/v1/asset
Request
Request may contain the following parameters
| Parameter | Description | Value |
|---|---|---|
| page | Page number for pagination (0-indexed). Each page contains 200 items. Default is 0 (first page). | Any numeric value |
Response
Response contains a list of all assets fetched.
Error Scenarios
If the request is incomplete or incorrect, the API will return a corresponding error.
| Error Code | Error Scenario |
|---|---|
| 401 Unauthorised | Invalid access token provided |
| 403 Forbidden | Access token missing |
| 405 Method Not Allowed | Incorrect HTTP method provided |
This operation returns all public organisations.
Endpoint
GET /api/assessments/v1/organisation
Request
Request may contain the following parameters
| Parameter | Description | Value |
|---|---|---|
| page | Page number for pagination (0-indexed). Each page contains 200 items. Default is 0 (first page). | Any numeric value |
Response
Response contains a list of all fetched public organisations.
Error Scenarios
If the request is incomplete or incorrect, the API will return a corresponding error.
| Error Code | Error Scenario |
|---|---|
| 401 Unauthorised | Invalid access token provided |
| 403 Forbidden | Access token missing |
| 405 Method Not Allowed | Incorrect HTTP method provided |
Support and Feedback
For technical inquiries or troubleshooting matters, please contact the Portal Support Team. When reaching out, please ensure that you provide comprehensive and detailed information regarding your issue. This will help the Support Team to address your concerns more efficiently and expedite the resolution process.
If you wish to share suggestions for improving API features, enhancing documentation, or advancing support services, please contact the Support Team. Your constructive feedback is valued and will contribute to the ongoing development and refinement of our services.