Get Some More REST

Over the last year and a half I’ve written multiple blog posts about X-Road and REST. Those blog posts have covered implementation plans, technical design details and release of the first X-Road version with REST support – the version 6.21.0 that was released in April 2019. All in all, the blog posts have covered the whole REST support journey from design to implementation and release. Currently we’re putting the finishing touches on the second stage of the REST support implementation which provides even more built-in REST-related features. The results are included in the version 6.22.0 that will be released in October 2019.

And for the readers interested in the technical details on source code level, the code implementing the REST support is available in the develop branch of the X-Road master repository on GitHub.

For clarity, adding support for REST does not mean dropping support for SOAP. No changes are required to information systems consuming and producing SOAP services via X-Road. Instead, the two architectural styles can co-exist side by side which means that all the current SOAP services are supported in the future too.

Basic Support for REST

The version 6.21.0 already provided a basic support for consuming and producing REST services:

  • Basic REST functionality

    • Message exchange with signing and time-stamping

    • Message logging with archiving

    • Downloading and verification of log records

  • Adding a REST service using an URL

  • Operational monitoring of REST services

  • Service-level authorization

  • Certificate based authentication (clients + services) 

The version 6.22.0 will provide all the REST related features included in the previous version plus a set of whole new features. Let’s find out what they are!

Metaservices for REST

Metaservices are built-in Security Server services that can be used by X-Road member organisations to discover what services provided by other members are available and download the service descriptions of these services. Until now the metaservices have been available over SOAP only, but starting from the version 6.22.0 the metaservices are available over REST too. The responses of the REST metaservices are always returned in JSON as the Security Server does not currently support other content types in the responses.

In the version 6.21.0 the SOAP versions of the metaservices return information about available SOAP and REST services. This is somewhat confusing as a SOAP client is not very likely to be interested in receiving information about REST services, and vice versa. Therefore, in the version 6.22.0 the functionality has been changed so that the SOAP versions contain information about the available SOAP services only and similarly, the REST versions contain information about the available REST services only. This means that in case information about all the available SOAP and REST services needs to be collected, both SOAP and REST versions of the metaservices must be invoked.

More detailed information about the metaservices can be found in the Service Metadata Protocol for SOAP and the Service Metadata Protocol for REST.

Support for OpenAPI 3 Descriptions

Existing REST services can be published in X-Road as-is – just like in the version 6.21.0. Unlike with SOAP services, the Security Server does not require X-Road specific information to be present in the responses returned by REST services. Certain X-Road-specific information is still included in the response message returned to a client information system, but the Security Server takes care of adding the required information to response message’s HTTP headers.

In the version 6.21.0 publishing a REST API is done by defining the base URL of a REST API and a service code. This is still possible in the version 6.22.0, but in addition it is possible to publish a REST API using the OpenAPI 3 Specification. When a new REST API is published it is possible to choose whether it is done using the base URL of the API or the URL of an OpenAPI 3 description of the API. The description can be provided in both JSON and YAML formats. This means that providing an OpenAPI 3 description is supported, but not mandatory. All REST APIs added using the version 6.21.0 will continue to work without any changes in the configuration.

Image 1. Adding a REST API in the version 6.22.0.

Image 1. Adding a REST API in the version 6.22.0.

The first benefit of providing OpenAPI 3 description is that other X-Road members can query the OpenAPI description using the new getOpenAPI metaservice – just like it is possible to query WSDL descriptions of SOAP services using the getWsdl metaservice. Another benefit of publishing an OpenAPI 3 description is that the Security Server reads all the API endpoints defined in the description and they become visible in the Security Server UI. The endpoints can then be used in access rights management – more about that later.

Image 2. List endpoints of a REST API.

Image 2. List endpoints of a REST API.

In addition, it’s also possible to add endpoints manually. However, manually created endpoints are not visible to other X-Road members through the getOpenAPI metaservice, but they can be used in access rights management just like the endpoints read from an OpenAPI description. Manually created endpoints can be updated and deleted by Security Server administrators. Instead, endpoints read from an OpenAPI description cannot be manually updated or deleted. They can be updated and/or deleted by updating the OpenAPI 3 description and then refreshing it on the Security Server. The same logic applies updating SOAP services through WSDL descriptions.

Image 3. Adding an endpoint manually.

Image 3. Adding an endpoint manually.

Besides access rights management, the Security Server does not use the endpoint-related information for anything else, e.g. the Security Server does not validate if an endpoint defined in a request by a client information system exists under an API or not. In other words, if a client information system has sufficient access rights to invoke an API endpoint, the Security Server forwards the request to the specified endpoint without any further validations.

More Fine-Grained Authorisation

In the version 6.21.0 REST APIs are authorized on the API level. In practice, this means that access rights are defined for all endpoints of an API. Sometimes this is OK, but other times it might be needed to define access rights on more fine-grained level, e.g. access to a specific endpoint only or only read access, but no permissions to add or modify data. The use of endpoints makes it possible to define access rights on more fine-grained level.

Starting from the version 6.22.0 it’s possible to define access for REST APIs on two levels: REST API level and endpoint level. In general, a REST API usually has multiple endpoints. When access rights are defined on the API level, they apply to all the endpoints of the API. Instead, defining access rights on the endpoint level enables more fine-grained access rights managements as access rights are defined using HTTP request method and path combination. Therefore, it is possible to define access rights for a single endpoint or alternatively for a subset of endpoints using wildcards.

When a client application has access rights on the API level, it means that the client can access all the endpoints of the API. In case clients must not have access to all the endpoints, then access rights must be defined on the endpoint level. Security Server’s access rights management only supports allowing access – explicitly denying access is not supported, e.g. allow access to all endpoints on API level and then deny access to a single endpoint is not supported.

What’s Next?

The version 6.22.0-beta is already out and the official release version 6.22.0 will be released in October 2019. However, the beta version already provides all the REST-related features included in the final release. The last weeks are reserved for fine tuning and testing.

The REST support implementation has been done in phases which means that REST-related features have been added along several X-Road versions – every new version adding something new. However, the version 6.23.0 does not have any planned new REST-related features yet, but it’ll likely contain smaller improvements to existing features, e.g. performance optimisations. In addition, we hope to receive feedback and enhancement requests from you regarding the exiting REST functionality. Improvements and new features may be added to the roadmap based on the received feedback.

In case you have not checked out the X-Road REST support yet, it’s time to do it now!