how x-road supportsrest apis?
TRANSCRIPT
How X-Road Supports REST APIs?
PETTERI KIVIMÄKI, CTO @pkivimaPUBLIC ADMINISTRATION – PRIVATE SECTOR API CODESIGN, ONLINE, 25 SEPTEMBER 2020
What is X-Road
Point-to-Point – X-Road
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.
X-Road Architecture
What Is X-Road
Support for REST APIs
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.
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.
X-Road REST Support
X-Road Message Protocols
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.
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
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.
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.
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).
Monitoring, Statistics and API Catalogue
The Finnish API catalogue:
https://liityntakatalogi.suomi.fi/en_GB/
