The aim of this article is to describe how to provide REST accessibility to TrustedX services. In other words, how to implement a REST interface for accessing these services (TrustedX REST API).
Advantages of having a REST API
The main advantage of accessing TrustedX web services through a REST API is its simplicity. In general, web services that can be accessed through a REST interface are very easy to use, which simplifies the programming and client maintenance thereby resulting in the consequent cost reduction.
In addition, REST access to TrustedX web services reduces the coupling between TrustedX and the clients who consume these services, safeguarding them from possible changes to these services.
Different approaches for implementing a REST API on TrustedX
In REST examples an RPC (Remote Procedure Call) approach to the TrustedX REST API has been adopted. According to this approach (REST-RPC), each of the TrustedX functions is considered a "resource" capable of providing a representation of the status variation that should be experienced by any application that accesses it (GET, POST) and provides it with a representation of a certain part of its status (i.e. a part that has certain semantics) as input.
For example, if an application has obtained an entity’s digital certificate by any means, it can be considered that the information corresponding to the digital certificate is part of the current status of the application in question. It can also be considered that it is possible to "augment" (i.e. change) the status of the application with information concerning the certificate’s validity at that time.
To this end, the application performs a POST on the resource that conceptually corresponds to the ability of TrustedX to validate certificates (e.g. certificates/validation) and offers as input a text representation (i.e. in XML) of the digital certificate whose validity it wants to know. The TrustedX resource (i.e. the digital certificate validation function) then obtains information on the certificate's validity and returns to the consuming application a text representation (i.e. in XML) of the information which, when received by the application, becomes part of its status.
The REST-RPC approach is appropriate when an application wants to perform security functions on the data that is part of its status and does not want this data or the data resulting from the execution of security functions to be "published" as resources that are accessible outside the status. This is, for example, the scenario of the validation of a digital certificate obtained by an application. The application wants to know if the digital certificate it has is valid (i.e. the digital certificate that is part of its status) and not the validity of a "resource-certificate" that is supposedly the same as the one that is part of its status, but is located outside it.
In other cases, however, it may be more advisable to adopt a ROA (Resource Oriented Architecture) approach when implementing a TrustedX REST API. In general, this approach will prove to be the best in situations where data that is initially part of an application’s status may generate resources that can be manipulated outside it. A clear example of this scenario is REST access to the TrustedX signature custody service. In this scenario, using data that is part of an application's status (e.g. data to be signed), TrustedX generates a resource (e.g. the signing of such data) for which it goes on to handle its maintenance (e.g. periodically updating the signature with time stamps and other evidence of non-repudiation) and of which it can provide a representation to any application that requests it.
Implementation of the REST API by configuring the SmartGateway component
Strictly speaking, there is no REST API that can be considered "the" REST API of TrustedX but, by properly configuring the SmartGateway component, any REST API that "makes sense" and adapts to the specific features of a certain scenario can be implemented on TrustedX.
In general terms, a REST API can be implemented on TrustedX services by defining a set of XML pipelines. Thus, each pipeline encapsulates a specific TrustedX functionality and is executed every time any of the methods (HTTP-POST, HTTP-GET) of the "resource's" interface, through which the SmartGateway component encapsulates that pipeline, is invoked. In fact, for the pipeline to be executed it must also meet the conditions that the SmartGateway component has established for it (e.g. one of the parameters of the request HTTP message’s URI has a certain value, the message-body of the request HTTP message contains a certain XML element).
Following a philosophy consistent with that of the services (signature, verification, validation, etc), each XML pipeline defined in TrustedX is included in a SmartGateway component rule which, in turn, can be included in one or more policies, also of the SmartGateway, and that has a set of associated conditions that determine its application and, therefore, the pipeline execution.
In addition, each SmartGateway policy has a list of URI (resource identities) associated to it, so they are also associated to each of the rules (i.e. pipelines) that fall within the policy (e.g. a typical case involves associating a single URI to each policy).
As a result, for TrustedX in the REST context, an action that is requested on the resource that is identified by a given URI is an action to be executed according to the SmartGateway policy to which the URI is associated. This means that the requested action will lead to the execution of the pipeline that is contained in the first applicable rule of the policy, that is, the first one for which TrustedX verifies that their conditions are met.