As you already know, NIIS has been working on the X-Road REST support since spring 2018 when a survey regarding the topic was done. The results did not leave any room for doubts – 93 % of the participants wanted X-Road to support REST. After the survey NIIS organized an X-Road REST support ideation and planning workshop in Tallinn in May. The aim of the workshop was to get more insight on implementing REST support from real X-Road users. The feedback received from the workshop has been used as an input for the following phases of the planning process. Now the planning has reached a state where the designed implementation approach can be shared with the X-Road community. Let’s take a look where we are today.
From SOAP…
To be able to better understand the selected approach for implementing REST support, let’s have a look at the current SOAP based implementation first.
Image 1. Current SOAP based implementation.
Currently X-Road has two message protocols: X-Road Message Protocol and X-Road Message Transport Protocol. X-Road Message Protocol defines how service consumers and service producers communicate with Security Server. The protocol is based on SOAP profile 1.1 and it comes with some X-Road specific limitations and additional requirements, e.g. support for synchronous request-response operations only, some mandatory SOAP headers are required, document/literal style SOAP body is required.
Instead, X-Road Message Transport Protocol is a proprietary protocol that defines how Security Servers communicate with each other. The protocol uses HTTP 1.1 over TLS and MIME multipart framing. The protocol wraps the X-Road Message Protocol payload and adds some additional authentication data and message signature. The key limitation of the current implementation is that only SOAP payload is supported.
…to REST
First, let’s define what REST means in X-Road’s context. Unlike SOAP that is a protocol with a detailed specification, REST is an architectural style consisting of best practices and guidelines. In X-Road’s case supporting REST means consuming and producing REST-style APIs via X-Road. A loose definition would be supporting JSON and/or XML over HTTP.
Image 2. Supporting SOAP and REST.
To be able to support REST-style services some changes to the current implementation are required. In addition to the current X-Road Message Protocol for SOAP, a new X-Road Message Protocol for REST will be created. The protocol will define how REST-style service consumers and service producers communicate with Security Server. The current X-Road Message Protocol for SOAP will remain unchanged – no changes are required to SOAP service consumers and service providers when REST support will be added. For clarity, adding support for REST-style services does not mean dropping support for SOAP services.
Adding support for REST-style services means that also X-Road Message Transport Protocol must be updated – a new extended version of the protocol will be created. The protocol will be changed so that the transport message will contain in place of SOAP request part a more generic payload part that can contain SOAP, JSON, XML etc. In fact, Security Server will not set any restrictions to the content type of the payload that is transferred between a service consumer and a service provider. The content type of the payload is defined using “Content-Type” HTTP header that is transferred between a service consumer and a service provider just like the payload itself.
Image 3. X-Road transport message before and after REST support is added.
In practice, the payload is transferred as-is – by default, Security Server does not modify, convert or validate the processed payload. However, validating that XML and JSON payloads are well-formed might be implemented. In general, services must be consumed using their native implementations – SOAP or REST. If a service provider wants to provide both SOAP and REST versions of the same service, the provider must implement both versions. In other words, Security Server will not provide automatic SOAP-REST conversion. In case automatic SOAP-REST conversion is needed, REST Adapter Service X-Road extension could be used. REST Adapter Service is an off-the-shelf component that provides an X-Road compatible REST-SOAP converter. The service supports a limited set of use cases.
The built-in REST support will have some limitations too. The implementation is restricted to request-response messaging model and it does not support HTTP streaming. Supporting these features would require some bigger changes to the X-Road architecture and therefore, they’re of out scope of REST support implementation.
Design goals
Backwards compatibility is one of the most important design goals when implementing support for REST-style services. The behavior of SOAP payload will stay compatible with the current implementation. This means that no changes are required to information systems consuming and producing SOAP services via X-Road.
When designing X-Road Message Protocol for REST, the aim is to design the interface for REST clients and services as future-proof. This means that the protocol will remain the same in the future versions of X-Roads which makes migrating to new X-Road versions significantly easier. Instead, the X-Road Message Transport Protocol, the protocol used between Security Servers, may change in the future versions of X-Road, but that does not have an effect on the service consumers and producers as long as X-Road Message Protocol for SOAP and REST remain unchanged.
One of the guiding principles in designing the X-Road Message Protocol for REST is the ease of use for both service producers and service consumers. In practice, this means that consuming and producing REST-style services via X-Road should be possible without an additional adapter service component. X-Road specific information required by Security Server (e.g. service client identifier, service provider identifier, message id etc.) should be transferred and processed so that existing REST-style services and clients can be connected to X-Road without making changes to services and clients to be connected. Therefore, X-Road specific information required by Security Server must be transferred outside of the message payload, in HTTP headers or URL parameters, for example.
Your input is needed!
The next phase in the REST support implementation process is a technical proof of concept (PoC) for validating the feasibility of the described approach before starting the actual implementation. The PoC has already started and the aim is to complete it in October.
Another task to be completed before starting the implementation is the definition of X-Road Message Protocol for REST. The protocol defines how REST-style service consumers and service producers communicate with Security Server. I have not covered the protocol in more detail in this blog post intentionally, because the first draft version of the protocol has just been completed and it is now available for comments. All the feedback will be reviewed, and the protocol will be further developed based on the received input.
NIIS welcomes everyone to comment the protocol draft! It is possible to leave comments until 18th October 2018.