Four common REST pitfalls

Justin James talks about four things developers do when designing REST services that make it very difficult to work with properly.

In the last several months, I have done integrations with a number of RESTful Web services. I understand why REST is popular; SOAP is a huge hassle to handle by hand, so if your system lacks sophisticated SOAP processing tools, it is easier to deal with REST. In addition, REST is not so bad when working in a dynamically typed language. That said, there are some things developers do when designing REST services that make it very difficult to work with properly. I'll look at four of these pitfalls and show what you can do to make life easier for the folks using your REST services.

1: Incorrect documentation

I haven't looked into REST service creation with all of the different systems out there, but from what I've seen, at least some of them do not have an easy, reliable way of automatically generating documentation. Every REST service I've worked with lately has severely inaccurate documentation.

When working with SOAP, this is less of an issue; the Web Service Definition Language (WSDL) is automatically generated, so even if your written documentation is wrong, the WSDL functions as the correct reference material. But with REST, if you are manually generating the documentation, it must be flawless. Maybe if your customers are always consuming the data from a language like Ruby you have some wiggle room, but when working with a statically typed language, bad documentation leads to all sorts of bad errors. Actually, that's a good thing, under the "fail fast" principle. All the same, get your documentation straight.

2: Incomplete documentation

Another big problem I keep running into with REST services is documentation that is incomplete. The documentation may be correct, but it is missing vital information. For example, if a value is going to be null, will the XML element be omitted entirely, or will its contents be blank? Is there a difference between an empty value, and a value that is not there at all? Are the elements in dates zero padded? When you provide a code, what exactly do the codes mean?

These are very real questions and problems when working with the service. Some of these issues are smoothed over by using a library like RestSharp in .NET, but others are beyond technical and are business logic questions. When writing your documentation, you need to assume that the person reading it has no idea what your internal logic is, and you need to spell everything out in excruciating detail. Again, this is something that SOAP handles really well, but with REST, it is up to you to document it.

3: Inconsistency

I have seen REST services that do different things in similar circumstances for no good technical or business reason. For example, the REST services might use an attribute to convey an item's status in one part of the service, but use an element for it in another part of the service. This inconsistency can drive the person using the service nuts. Once you establish a means of doing things, do it consistently throughout the entire service.

4: Backwards compatibility

You should try your best to make your service backwards compatible with previous versions. If you ever need to make a breaking change, you should maintain the previous versions and make sure that your users need to do something deliberate (such as changing the endpoint information) to access the newer version. If you require a registration of clients, you should notify them and provide a sunset window to close out the previous version of the service, carefully monitoring its usage before shutting it down.


Most of these tips are true for any kind of external library, but they are even more imperative with a REST service because they act much like dynamic code does but are often consumed by static code; as a result, discrepancies in documentation and significant changes have a high cost to adapt to on the usage side of things.

If you keep things well and accurately documented and consistent and don't make breaking changes without requiring a change in the consuming code, it will go a long way towards having happy users.