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

The JSON standard has quickly become important on the Web. At first, it was convenient because it allowed JavaScript to easily consume Web service output with minimal coding required. Now there are a lot of libraries to allow server-side and native client code to consume JSON as well.

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

One of the best things you can do is provide sample code for developers to use. Make sure that your code is given for all the major languages or runtimes out there: Java, .NET, JavaScript, Ruby, and Python, at a minimum. If you have to, hire a consultant to put together this code, since it is absolutely vital for adoption of your service. Make sure that you license your sample code in a way that will allow your customers to use it with no repercussions, such as the MIT or BSD licenses.

Additional resources