Service Metadata Protocol for REST
X-Road: Service Metadata Protocol for REST
Technical Specification
Version: 0.7 Doc. ID: PR-MREST
Version history
Date | Version | Description | Author |
---|---|---|---|
29.07.2019 | 0.1 | Initial version | Ilkka Seppälä |
06.08.2019 | 0.2 | Add getOpenAPI description | Ilkka Seppälä |
09.10.2019 | 0.3 | Clarify the listCentralServices response type | Jarkko Hyöty |
07.11.2019 | 0.4 | Clarify getOpenAPI description | Ilkka Seppälä |
05.10.2021 | 0.5 | Update listMethods and allowedMethods | Ilkka Seppälä |
17.04.2023 | 0.6 | Remove central services support | Justas Samuolis |
10.05.2023 | 0.7 | Security Categories removed. | Justas Samuolis |
Table of Contents
License
This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/
1 Introduction
X-Road Service Metadata protocol [PR-META] describes how X-Road metaservices can be called via SOAP interface. This specification complements it by describing REST call mechanisms.
REST metaservices conform to X-Road Message Protocol for REST [PR-REST].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and " OPTIONAL" in this document (in uppercase, as shown) are to be interpreted as described in [RFC2119].
1.1 Terms and abbreviations
See X-Road terms and abbreviations documentation [TA-TERMS].
1.2 References
[PR-META] X-Road: Service Metadata Protocol. Document ID: PR-META.
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels, Internet Engineering Task Force, 1997, https://www.ietf.org/rfc/rfc2119.txt
[TA-TERMS] X-Road Terms and Abbreviations. Document ID: TA-TERMS.
[PR-REST] X-Road: Message Protocol for REST. Document ID: PR-REST.
2 Retrieving List of Service Providers
For retrieving the list of service providers listClients metaservice is used. It can be invoked with simple HTTP GET to right URL. Service output format is controlled with Accept header. The details of listClients are described in [PR-META].
4 Retrieving List of Services
X-Road provides two methods for getting the list of services and service endpoints offered by an X-Road client:
listMethods
lists all REST services and service endpoints offered by a service provider.allowedMethods
lists all REST services and service endpoints offered by a service provider that the caller has permission to invoke. Notice that the endpoints may contain wildcards and the amount of concrete endpoints may actually be larger. Generally, fetching the OpenAPI service description is the preferred method for discovering service endpoints.
Both methods are invoked as regular X-Road REST services (see specification [PR-REST] for details on the X-Road REST protocol).
The serviceId MUST contain the identifier of the target service provider and the value of the serviceCode element MUST be either listMethods
or allowedMethods
.
Request example
HTTP request headers
The body of the response message MUST contain a list of services and service endpoints provided by the service provider (in case of listMethods) or open to the given client (in case of allowedMethods). The response SHALL NOT contain names of the metainfo services.
Annex A contains the OpenAPI description of the REST metadata services.
Annexes B.1 and B.2 contain example response messages for services, respectively.
5 Retrieving the OpenAPI description of a Service
X-Road provides a metaservice for fetching service descriptions of REST services.
getOpenAPI
returns the OpenAPI service description of a REST service
The method is invoked as regular X-Road REST service (see specification [PR-REST] for details on the X-Road REST protocol).
The serviceId MUST contain the identifier of the target service provider and the value of the serviceCode element MUST be getOpenAPI
.
The query parameters must contain serviceCode=xxx
where xxx is the service code of the REST service we want to get the service description from.
Request example
HTTP request headers
Note that fetching the OpenAPI service description respects the "Verify TLS Certificate" setting of the service.
The body of the response MUST contain the OpenAPI service description of the REST service indicated by the query parameters.
Annex A contains the OpenAPI description of the REST metadata services.
Annex B.3 contains an example response message for the service.
Annex A Service Descriptions for REST Metadata Services
Annex B Example Messages
B.1 listMethods Response
curl -H "accept: application/json" -H "X-Road-Client:INSTANCE/CLASS1/MEMBER1/SUBSYSTEM1" "https://SECURITYSERVER:443/r1/INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/listMethods"
B.2 allowedMethods Response
curl -H "accept: application/json" -H "X-Road-Client:INSTANCE/CLASS1/MEMBER1/SUBSYSTEM1" "https://SECURITYSERVER:443/r1/INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/allowedMethods"
B.3 getOpenAPI Response
curl -H "accept: application/json" -H "X-Road-Client:INSTANCE/CLASS1/MEMBER1/SUBSYSTEM1" "https://SECURITYSERVER:443/r1/INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/getOpenAPI?serviceCode=listFirms"
Last updated