Web Development optimize

10 things you should do to write effective RESTful Web services

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

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

About

Justin James is the Lead Architect for Conigent.

2 comments
Deadly Ernest
Deadly Ernest

1. When referring to something by it's acronym, it's usually polite to give the full name early on so people don't get confused about what you're talking about. For those that don't know what the subject it, it's - Representational State Transfer (REST), a style of software architecture for distributed systems. See wiki for more info: http://en.wikipedia.org/wiki/REST 2. Before getting too heavy into making a web site very REST capable, or any other type of capability, please take the time out to make sure you need that level of technology or technique and that a much simpler technique or method won't do the job for less trouble to the site visitor. Way to many sites today are way over designed and over coded and use lots of scripts when the same result can be achieved with a fraction of the download by using basic html code. I recently went to a web site and found I could NOT fill in the information the company wanted on the corporate web site as the data collection / input forms were created in Flash and Flash has not been supported on Linux for some time, nor does the current versions of Flash work well with the much older versions of Windows - I hooked up my old Win 98SE system I rebuilt for games and tried the site; I got an 'update Flash' message and when I tried to update I got told there is no current version of Flash for Win 98. In short, think about the site visitors and what they may be using to get access as not everyone has high speed broadband Internet.

fifidonkor
fifidonkor

It is a framework. VisualBASIC or C# are both languages that work in .Net.