The lack of a service description language for REST services has caused some confusion in camps with a history of IDLs and WSDLs. WADL has attempted to fill the gap, but has received a mixed response amongst theorists and developers.
A REST architecture by definition has a Uniform Interface. The uniform interface is made up of a common "standard" set of application protocol messages such as those defined by HTTP, as well a common "standard" set of media types such at html and atom. The web attributes fairly low-level semantics to these media types. A more machine-centric REST architecture such as an enterprise architecture or a semantic web will have a richer set of types that incorporate sufficient semantics for the particular problem domain.
The method and media type facets of a uniform interface are generally heavy on human-understandable specifications. A REST architecture can generally tolerate this because there will be a much smaller set of specifications required than in a conventional enterprise architecture. Existing tools can be employed where this becomes unmanageable, for example XML schema.
The final facet of a REST service interface is the set of resource identifiers, and the detailed semantics of issuing specific requests such as GET and PUT upon these resources. In REST theory the structure of these identifiers must be uniform, but the set is expected to evolve over the lifetime of the architecture. The set of URLs on the Web is governed by individual service owners, and not by the IETF or the w3c.
The argument against a REST-specific interface description language is that the uniform interface of a REST architecture is already well served by existing human-readable and machine-readable technologies. Consumers of REST services should be coupled to the uniform interface at design time, then free to follow hyperlinks at run-time to interact with whatever services might be present in the architecture. There is a danger in promoting service description languages and consumer-visible service description in general that we will start introducing service-specific dependencies at development time to consumers. The natural outcome of this will be tight coupling and failure to meet various architectural objectives. In particular, the ability for the architecture to withstand incremental upgrade over a long period of time can easily be compromised by service-specific knowledge becoming encoded into clients.
The main use case for a service interface description language is at design time. This means that ideally we would not expose this language at all consumers of our REST services. Two basic use cases exist for such a language:
- To provide mass-publication of URLs to clients at run-time, and
- To assist in developing and analysing of service properties at development time
The first use case is fraught with problems both theoretical and practical. Firstly we have the risk that such a document will be used at design-time within clients, limiting the potential longevity of the architecture as a whole. Secondly, a language expressive enough for a machine to understand at run-time is either going to be extremely complicated or have fairly narrow applicability.
The second use case is more compelling. Here we are really looking into the computer-aided development of REST services without contravening architectural constraints. This is not to be discouraged. Here it is useful to consider what a REST service architect would likely do in developing a service.
We can safely assume in general that the uniform interface is designed, and any changes required of it to introduce our service are being negotiated in the appropriate forum. The service description language does not need to specify the generic meaning of methods or of media types. The service description can thus be reduced to a matrix:
| URI Template | Method | Media Types | Semantics |
|---|---|---|---|
| https://example.com/invoice/{invoice} | GET | application/invoice+xml | Retrieves the invoice information set of the specified invoice |
| https://example.com/invoice/{invoice}/paid | PUT | text/plain (xsd:boolean format) | Sets an invoice to paid or unpaid |
Method and media type identifier should be sufficient to reference a full specification of these facets of the uniform interface. The URI Template should describe one or more URIs that will be valid for the service or the set of services. Sufficient guidance on percent-encoding of characters should be available either implicitly or explicitly in order to guide developers and analysts. Semantics may require more detail, and should support similar descriptions to those that might be found in a javadoc or doxygen function description.
It is important that space exists to specify alternate document types to allow for evolution of the architecture's media types. For example, a service that once supported rss may need to evolve to additionally support atom in order to support both old and new service consumers. Different options in this column indicate a requirement to support content negotiation to return data in the specified format.
The addition of new service-specific methods and media types should be look upon as part of the gradual evolution of the REST architecture. Their specifications should not appear as part of the service specification, but instead be referenced by it. On the Web this means going through the standards bodies that govern the Web. In an enterprise this means going through the appropriate enterprise architecture team.
In some cases your service will be the first on the Web to make use of a particular method or media type. In these cases you will need to make a decision about whether you intend to blend your extensions into the fabric of the Web architecture or whether you intend to co-host your architecture with the Web. In the former case we are again talking about standardisation through bodies such as the IETF. In the latter case we are potentially talking about setting up a new governing body that meets the needs of your particular problem domain.
Importantly, a REST service description never sets out to define service-specific methods or media types. One service does not a REST architecture make. A REST architecture always consists of a set of services and their consumers operating through a uniform interface that does not expose service-specific or consumer-specific details at design time.
A service description language in support of computer-aided development and analyst-friendly REST service description will consist of the fields indicated above. Semantics are indicated for a specific method, on a specific set of URIs, with a specific set of content types. The service-specific interface of a REST service is defined by these fields.
For developers of software that implements services, this service-specific interface specification can be an invaluable reference and a sound source of information for user manuals and other integrator-visible documentation.
Benjamin