How X-Road SupportsREST APIs?
Transcript of How X-Road SupportsREST APIs?
![Page 1: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/1.jpg)
How X-Road Supports REST APIs?
PETTERI KIVIMÄKI, CTO @pkivimaPUBLIC ADMINISTRATION – PRIVATE SECTOR API CODESIGN, ONLINE, 25 SEPTEMBER 2020
![Page 2: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/2.jpg)
What is X-Road
![Page 3: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/3.jpg)
Point-to-Point – X-Road
![Page 4: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/4.jpg)
X-Road Provides
u Organization level authenticationu Machine to machine authenticationu Standardized messaging modelu Non-repudiation and logging of messages
u Digital signatures with timestamps and eSealsu Usage statisticsu Access rights managementu Address management and message routingu Transport level encryption.
![Page 5: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/5.jpg)
X-Road Architecture
![Page 6: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/6.jpg)
What Is X-Road
![Page 7: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/7.jpg)
Support for REST APIs
![Page 8: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/8.jpg)
REST?
u REST is an architectural style consisting of best practices and guidelines.
u In X-Road’s case supporting REST means consuming and producing REST-style API’s via X-Road.
u X-Road’s REST implementation supports transferring any contenttype over HTTP.u Message payload is transferred as-is, Security Server does not
modify, convert or validate the payload in any way.
![Page 9: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/9.jpg)
X-Road REST Support in a Nutshell
u Publish REST services with no changes to existing services.
u Publish REST service descriptions using OpenAPI 3.
u Consume REST services with minimal changes to existing clients.
u No restrictions on supported content types.
u Fine-grained authorization of REST endpoints.
u Metaservices for REST clients.
u All standard X-Road features included, e.g. organization and machine-to-machine level authentication, logging, time-stamping, monitoring etc.
![Page 10: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/10.jpg)
X-Road REST Support
![Page 11: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/11.jpg)
X-Road Message Protocols
![Page 12: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/12.jpg)
X-Road Message Protocols
u Separate message protocols for SOAP and REST-style servicesover HTTP:u X-Road Message Protocol for SOAP
u X-Road Message Protocol for REST.
u An extended version of X-Road Message Transport Protocol.u Transport message contains in place of SOAP request part a more
generic payload part that can contains SOAP, JSON, XML etc.
![Page 13: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/13.jpg)
Example Request
curl -X GET "https://petstore.niis.org/v2/pets/1124?foo=bar"
curl -X GET "https://{securityserver}/r1/{serviceId}/v2/pets/1124?foo=bar" -H "X-Road-Client: {client}"
Service called directly
Service called via X-Road
Service Method Description Parameters
/pets/{petId} GET Finds pet by ID petId - ID of pet to return
To invoke a service via X-Road instead of a direct service call it is enough to update the base URL of the service and add ”X-Road-Client” HTTP header to the request. The relative path to the serviceincluding path and URL parameters remains unchanged.
curl -X GET "https://ss1.example.com/r1/CS/ORG/1111/TestService/MyApi/v2/pets/1124?foo=bar" -H "X-Road-Client: CS/ORG/1111/TestClient”
For example
![Page 14: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/14.jpg)
Features
u Message exchange with signing and time-stamping.u No restrictions on the content-type - message payload is transferred as-
is.u Path and URL parameters, and HTTP headers are transferred as-is.u Message body, path and URL parameters, and HTTP headers are
included in the signature.u Support for OpenAPI 3:
u Add APIs using OpenAPI 3 specification (optional). Alternatively, APIscan be added using the API endpoint URL.
u Meta-service for querying services' OpenAPI definitions.
![Page 15: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/15.jpg)
Features
u Fine-grained authorization:u On REST API (service code) level – grant access to all endpoints under an API.u Endpoint (path + method) level authorization.
u Endpoints can be imported from OpenAPI specification or created manually.
u Message logging with archiving.u Logging of message body can be disabled – in that case path + URL parameters
and HTTP headers are not logged either.u By default the maximum body size to be logged is 10 MB, but the default value
can be overridden.
u Downloading and verification of log records.
![Page 16: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/16.jpg)
Features
u Metaservices for REST:u List of service providers (listClients).
u List of REST services offered by a service provider (listMethods).
u List of REST services offered by a service provider that the client hasa permission to invoke (allowedMethods).
u Retrieve OpenAPI 3 description of a service (getOpenAPI).
![Page 17: How X-Road SupportsREST APIs?](https://reader031.fdocuments.us/reader031/viewer/2022020620/61e294501ba72543436ff677/html5/thumbnails/17.jpg)
Monitoring, Statistics and API Catalogue
The Finnish API catalogue:
https://liityntakatalogi.suomi.fi/en_GB/