Classification of HTTP-based APIs

This table provides a classification of HTTP-based APIs. The classification achieves an explicit differentiation between the various kinds of uses of HTTP and provides a foundation to analyse and describe the system properties induced.

Providing distinct names for the API 'styles' overcomes the useless situation where APIs are named 'RESTful' and 'not so RESTful','almost RESTful', or 'unRESTful'. An API either adheres to REST's interface constraints or it does not and if it does not, there is no sense in referring to 'REST' in the API's name. Especially so because mentioning REST might cause the false impression that the achieved system would share the same system properties as RESTful systems.

They do not - and it is important to understand that the system being designed might not have the expected properties. For example, caching and visibility can be ruined by tunneling operations though action names in URIs.

The most important distinction to be made today is the one between the two HTTP-based API kinds HTTP-based Type I and HTTP-based Type II on the one hand and REST on the other hand. The former two, while not RESTful due to their violation of the hypermdia constraint, can be a reasonable design choice if the tight coupling they induce is acceptable for the given system. This might be the case if the expected life time of the system does not warrant the considerable work of designing a proper media type.

However, it must be explicitly understood that both API kinds, 'HTTP-based Type I' and 'HTTP-based Type II' lead to systems in which clients and servers are coupled by their original design and that the evolvability properties of RESTful systems are in no way induced.

Helping to understand these trade-offs is the goal of the following table.

Name Description Typical Signs REST Interface Constraints Example
(hover for link) Identification of Resources Manipulation of Resources through Representations Self-Descriptive Messages Hypermedia as the Engine of Application State
WS-* WS-* Web Services (SOAP) IDL (WSDL) describes interface, HTTP treated as transport. No - only service endpoint is identified by URI. No resources exposed. No - SOAP body contains operation name, message not transferred to manipulate resource state. No - message semantics depend on action specified in message body. No - Application state machine known at design time.
RPC URI-Tunneling APIs expose resources but operations are tunneled through action parameters in URIs. Design time descripton of URI space, typed resources, API-specific operations, action parameters specify operation, application specific failure codes.
Dangerous variant: tunneling unsafe operations ('delete account') through safe method (GET)
No use of WADL.		 OK No - URI contains action, message not transferred to manipulate resource state. No - message semantics depend on action specified in URI No - URI space and application state machine known at design time.
HTTP-based Type I Resources are exposed, HTTP methods used correctly, use of generic media types (e.g. application/xml) Design time descripton of URI space, typed resources, design time WADL (description of available resources,methods and representations), API describes schema for generic media type(s) used, operations are translated to client-side OO-API, for example 
Order order = new Order("http://foo/orders/1);
order.ship();
OK OK No - message semantics implied by specific schema used is only known to client and server but not intermediaries. No - application state machine is known at design time. Assumptions about available representations and transitions are hard-coded (or configured). Client and server are coupled by original design.
HTTP-based Type II Resources are exposed, HTTP methods used correctly, use of specific media types (e.g. application/atomsvc+xml) Design time descripton of URI space, typed resources, design time WADL (description of available resources,methods and representations), API description lists specific media types and for which resources they are used, operations are translated to client-side OO-API, for example 
Order order = new Order("http://foo/orders/1);
order.ship();
Ok Ok Ok No - application state machine is known at design time.Assumptions about available representations and transitions are hard-coded (or configured). Client and server are coupled by original design.
REST Adherence to all REST constraints All service description comes in the form of media type (and link relation etc.) specifications, client only knows entry bookmark (URI) and media types and no specifics about the particular service. Client proceeds through application by looking at one response at a time, each time evaluating how best to proceed given its overall goal and the available transitions. Methods to use are known from media type (and link relation etc.) specifications or selected at runtime based on forms (form semantics known from media type specifications). Ok Ok Ok Ok

1This might be debatable, but Google does a good job in specifying an independent format as opposed to saying: "Responses look like this XML or like that XML.

Effect on System Properties and Cost

The architectural constraints that constitute the REST style induce certain desired system properties into a conforming architecture. When any of these constraints are (accidentally or deliberately) removed in a given system, that system will not have the same system properties as a RESTful system.

In order to understand the effect of removing a certain interface constraint the following table provides an overview of the impact upon selected system properties.

Removing constraints can reduce start-up cost which in some scenarios might be of more concern than long-term maintenace- or evolution cost. The right hand side columns of the table place the impact of removing constraints into an overall context of start up-, maintenance- and evolution cost.

Name Performance Visibility Modifiability Simplicity Scalability Cost
(hover for link) Network Performance Network Efficiency Evolvability Extensibility Initial Cost Maintenance Cost Evolution Cost
WS-* No explicit focus on coarse grained (document oriented) messages, accidental design towards fine grained- or control messages can degrade network performance. The lack of any visibility completely removes the ability to use caching. Responses should always be marked as non-cacheable to avoid that existing HTTP caches negatively impact the application. No visibility because meaning of message depends on understanding action. The effect on trust will usually be that the filtering party blocks all requests to the single service endpoint. Tight coupling of client and server prohibits independent evolution. Tight coupling decreases extensibility. Overall variation is not constrained, though best-practices exist (which is an advantage over RPC URI-Tunneling). Poor vendor standards compliance. Server statelessness not guaranteed by a constraint. Scalability depends on application design. Very high startup cost due to inherent complexity of the standards, learning about vendor differences, learning of development tools, designing application specific failure model and caching. Finding knowledgeable staff. Complexity increases maintenance cost, high up-to-speed effort for new staff High evolution cost due to tight coupling, vendor lock-in despite 'standards'
RPC URI-Tunneling No explicit focus on coarse grained (document oriented) messages, accidental design towards fine grained- or control messages can degrade network performance. The lack of any visibility completely removes the ability to use caching. Responses should always be marked as non-cacheable to avoid that existing HTTP caches negatively impact the application. No visibility because meaning of message depends on understanding the action. The effect on trust will usually be that the filtering party blocks all requests to the corresponding application. Tight coupling of client and server prohibits independent evolution. Tight coupling decreases extensibility. Overall variation is not constrained, no best-practices exist, complexity nightmare Server statelessness not guaranteed by a constraint. Scalability depends on application design. Medium to low start-up cost (not as low as HTTP-based Type I), failure model must be defined, caching must be considered, safety issues of HTTP methods must be addressed. Considerably high maintenance cost due to unconstrained complexity and missing best-practices, high up-to-speed cost for new staff, hard to debug. High evolution cost due to tight coupling and unconstrained degree of variation (induces complexity), evolution impact analysis difficult.
HTTP-based Type I Coarse grained, document oriented messages are encouraged. Visibility induced by the uniform interface constraint enables caching which improves network efficiency. The degraded visibility due to the generic media types does not affect caching. Reduced visibility because only client and server understand message payload. This negatively affects trust, if the filtering party looks into message body (which is unusual); no negative impact on caching. Tight coupling of client and server prohibits independent evolution. Undecided Increased by interface uniformity (though missing message self-descriptiveness and application specific schemas decrease simplicity) Server statelessness encouraged by best practices (definitely not hindered by approach in general).Possibility of erraneous design equivalent to HTTP-based Type II and REST Lowest start-up cost due to lack of need to design or extend media type. HTTP mechanics are leveraged, no need for design of operations, failure model or caching. Medium due to possibly decreased simplicity (possible high degree of variation of message formats). Up-to-speed effort reasonable but depending on degree of message format variation. Easy to find knowledgeable staff. High evolution cost due to tight coupling. Server owners need to consider clients when upgrading.
HTTP-based Type II Coarse grained, document oriented messages are encouraged. Visibility enables caching which improves network efficiency. Messages are self-describing and can be understood by intermediaries. This is the foundation for caching and trust (firewall admins can understand the messages and allow exactly the traffic they want to let through) Tight coupling of client and server prohibits independent evolution. Undecided Maximised by interface uniformity and message self-descriptiveness. Server statelessness encouraged by best practices (definitely not hindered by approach in general). Possibility of erraneous design equivalent to REST Can be high if not possible to leverage existing media types. has media type design issue, but has easy, straight-forward client side programming model Low due to simplicity, easy to find knowledgeable staff, excessive extending of existing types can decrease simplicity. High evolution cost due to tight coupling. Server owners need to consider clients when upgrading.
REST Coarse grained, document oriented messages are encouraged. Visibility enables caching which improves network efficiency. Messages are self-describing and can be understood by intermediaries. This is the foundation for caching and trust (firewall admins can understand the messages and allow exactly the traffic they want to let through). Coupling between client and server is removed, server owners need not know about client particularities to evolve the servers without breaking clients. Increased by loose coupling. Maximized by uniformity of connectors and identifiers Message self-descriptiveness constraint mandates message statelessness which in turn mandates the stateless server constraint. The latter guarantees scalibility. Considerably high learning curve, cost of proper media type design, highest client side effort (burdon of loose coupling is placed on client side programming model) Low due to simplicity, easy to find knowledgeable staff. (While it is considerable effort to design a proper media type, understanding it has a low entry barrier) REST optimizes for evolvability. Server owners need not consider impact of evolution on clients.

Immediate Conclusions

  1. WS-* and RPC URI-Tunneling are the worst approaches from a benefits/effort ratio point of view. The lack of best practices makes RPC URI-Tunneling considerably worse. Basically, a designer/developer can just go off and go wild.
  2. The start-up cost of HTTP-based Type I APIs is actually smaller than the one of RPC URI-Tunneling, mostly because the former leverages HTTP mechanisms (methods, failure model, caching). There is no justification whatsoever to apply RPC URI-Tunneling - always at least use HTTP-based Type I.
  3. Depending on the degree to which existing media types apply to the problem domain HTTP-based Type II should be considered over HTTP-based Type I because the start-up cost is almost identical. A transition from HTTP-based Type II to REST at a later point in time, however, is rather easy (from the server side point of view).
  4. Turning a HTTP-based Type II API into a REST API might be as easy as deleting the API documentation.
  5. If you are to any degree concerned with long term maintenance- and evolution cost (which any enterprise IT system owner will need to be), REST is the best solution despite the start-up cost. The start-up cost will amortize in the long run.

References

Wish-List for Next Release

History

25 Feb 2010 - Initial version

26 Feb 2010 - Added impact analysis table and conclusions, added references and wish list

Thanks for discussions that lead to this document and for feedback to: Stefan Tilkov, Mark Baker, Felipe Gaúcho, António Mota, Michael Hausenblas, Mike Amundsen, Darrel Miller

--Jan Algermissen

 

© 2010 NORD Software Consulting, Terms of Use: Creative Commons License