When we started building a new Web API for our business we wanted to build a really great API and the answer on Internet was to build a RESTful API, Amy Palamountain revealed in a recent presentation at TechEd in New Zealand.
Is a RESTful API always a good solution to your problem? Amy thinks it depends on the context, but for public APIs her experience is that it should be RESTful and based on the core ideas of HTTP and the web.
SOAP, and other RPC (Remote Procedure Call) APIs, is about two execution contexts, on a client and on a server, where a client remotely invokes an action on the server. This is an action centric design, needing an upfront agreement which makes the client tightly coupled to the server. This is for Amy less suitable for public APIs as it’s not very accessible or flexible, e.g. a change in the server will likely break the client.
Amy's first step in a move from a RPC style is moving from actions to resources that expose domain concepts, e.g. entities. Another part of this move is embracing HTTP and URIs which makes an API more accessible and easier to use by being more consistent with the HTTP specification.
But there is still inherent knowledge about how to use the API which is baked into the client; a change in relations between the resources will still break the client and requiring a redeploy.
Next step in Amy’s strategy is adding hypermedia where links are the way to show how resources are related. Using links in a web API ensures that all needed information is included; there is no out of band information. Hypermedia thus removes the inherent knowledge that otherwise would be inside the client:
- Links show how resources are related to each other.
- Links show how to interact with the problem space, the next possible actions.
- Links enables dynamic addition and removal of options within the problem space when it evolves.
There are some practical problems though that needs some thought, especially on clients. Hypermedia APIs need hypermedia driven clients, the client must understand the media type used by the server. The media type describes the semantic meaning of e.g. links and forms.
In her presentation Amy uses an example with a server and two clients, one using resources and URIs, one using hypermedia, all written in C# using the ASP.NET Web API framework.