Editorials

When a Web Service is not RESTful

Recently I’ve come to understand that I have not fully the specifications of a RESTful API. In fact, most of my work would be called a Web Service API. There are some key distinctions between the two. You’ll know if you are following REST principles based on how your API is consumed.

While both a Web Service API and a RESTful API use URIs to communicate resources, there is a difference in how they are implemented. When using a RESTful API, the client only knows the root endpoint to the service. Receiving a response from the service returns the top of the object hierarchy with the available resources, and the URIs capable of utilizing the service. So, the client is able to discover APIs and consume the resources as they are returned.

By contrast, many Web Service APIs use the URI for communication, and Interact with clients using resources. The URIs are most often hierarchical. However, responses from on URI to the next don’t expose a map of where you can go based on what you have retrieved. The client is fully aware of the entire API. Changes to the service require changes to the client to enable new functionality.

While the client of a RESTful API service may not be aware of the entire API directly, it does have to implement to some degree the ability for the user to interact with the resources received. The value you gain by being more RESTful is that you can make modifications on the server side, maybe even change URIs significantly, and your client should adjust to those changes.

There’s a lot more to being RESTful than using hypermedia (resource mapping and URI resolution). But I find this specific feature to be a big distinction that radically changes how you write and consume services.

Cheers,

Ben