With the popularity of REST Web services on the rise, developers need to know how to avoid pitfalls and make their services the best they can be.
Over the last few years, we have seen RESTful Web services become popular for a number of reasons. Here are 10 things you should do to make your RESTful Web services as good as possible and easy for other developers to use.
1: Don't look for an official "REST standard"
REST Web services are a concept, not a standard. There is no requirement for your REST Web service to work any particular way. At the same time, though...
2: Adhere to standards anyway
...Your REST Web services should adhere to at least some standards! For example there is OAuth for authentication, JSON and XML for data, HTTP for the transport and control itself, and the URI standard. If you want a more complete package, OData is available as a larger item. Just because no one says "REST must adhere to these standards" does not mean you should just make up your own.
3: Make sure your documentation is flawless
With SOAP, there is the Web Service Definition Language (WSDL) system, which makes it fairly easy to work with a service if you have a tool to automatically generate code based on the WSDL. But with REST, services are less strictly defined, and they depend upon being called properly to work right. That means that the service documentation is critical. Make sure that if you are creating a REST Web service, the documentation is 100% correct.
4: Provide JSON output
5: Don't forget XML
Speaking of output, XML output is still as important as it always has been. Why support both XML and JSON? Because not every system can consume JSON, but if a system can make a Web service call, it will have a provision for XML processing. There are piles of legacy systems out there, for example, that work with XML but not JSON, and not all developers want to start mixing and matching JSON and XML. Make sure your service supports both formats. The "Accepts" header in the HTTP request is a good way to do this instead of having a parameter or different service URL.
6: Understand the verbs
One of the key concepts in REST Web services is that the functionality is in large part defined by the HTTP protocol. And the most fundamental part of this is the HTTP action verbs, such as GET and POST. While the basic functionality is well understood in REST, some ideas, like using PATCH to update only specific attributes of an entity instead of the entire entity, are still emerging.
7: Understand the importance of URI routing
RESTful Web services depend in large part on the URI to decide what to do. For example, in a "GET" request, the URI path typically contains the primary key value (or some other identifier) of the entity to retrieve. For instance, "http://www.example.com/service/entityname/76" would retrieve the entity with a name of "entityname" and a primary key value of 76. With REST Web services, the URI is not just a means of accessing the service, but a way of controlling it and signaling your needs.
8: Do not make changes without versioning the service
It will be tempting to maintain only one version of the service as you make changes. Do not do this! Make sure that you maintain separate versions each time you release changes. The easiest, most common way of doing this is to make the version number part of the URI to the service, usually in part of the path. The last thing people need is to have the service's functionality change without warning.
9: Stay in contact with your users
Because of the lack of automatic discovery, it is even more important that you stay in touch with your users and consumers. For example, when you release a new version of the service, you should send an email to users letting them know about it as well as providing information for the deprecation of older versions of the service.
10: Provide sample code
- Four common REST pitfalls
- Calling RESTful services from your Android app
- 10 skills for developers to focus on in 2012
- Use Web services to separate concerns and for code reuse
- .NET 4.5 and Visual Studio 11 Beta: What you need to know