Usage of RESTful API end-points has become the de facto standard since 2008. With the popularity of browser-based client frameworks (like AngularJS, Backbone.js or Ember.js), RESTful API end-points have found their way into corporate environments. Using the Spring Tool Suite (STS), it is quite easy to spin up a RESTful web service.

The focus of this article is to pose the question "is your RESTful API is doing what it should be doing?"

Common RESTful End-Points & HTTP Methods

The initial collection of end-points typically handles common database interactions for the RESTful API. Some examples are listed below:

Obtain a list of records or a single record (GET)

Create a new record (POST)

Update an existing record or a set of records (PATCH)

Delete a record (DELETE)

It is important to make sure the right HTTP method type is being used. The preferred method is listed in parenthesis for each example above. A common misuse is utilizing POST when PUT or PATCH should be called. The PUT method should be used when updating a resource completely through a specific resource, while the PATCH should be used when updating partial resources.

RESTful Service Validation

Rich client frameworks often provide excellent mechanisms for data validation. When paired with a sleek front-end framework (like Bootstrap), the user-experience can be quite pleasing. Often times, developers begin to rely on handing validation only on the client and forget about the RESTful API. Even if your service is isolated to a private network, validation should be part of your RESTful API.

A good rule of thumb is to treat your RESTful API as if it is running on a public network. Annotations make it easy to add most validation rules and RESTful services allow returning an HTTP error code when a validation error occurs. While the client framework will likely catch these errors prior to submission, you could handle parsing these errors as well.

RESTful Service Payload

I have seen a couple approaches when delivering payload back to the client as part of a RESTful service call. The most common is to return a payload of data that matches the underlying object.

As an example, if your end-point is looking for a list of active customers, the payload may appear similar to what is listed below:

Another payload pattern that I have seen returns a custom object, which also includes the data being requested. So, in the example above, the same list of active customers would be returned, but other items will also be returned:

The list of active customers is contained inside the resultData list. Additionally, the payload includes information for the following items:

responseCode = the HTTP response code

responseMessage = used to relay error or information messages

pageNumber = the current page number of the data being shown

totalPages = the total number of pages for the original list of data

itemsPerPage = the number of items for a given page

The second example can be useful when wanting to keep track of items that accompany the request. Also, since the response code was also included, it saves the client from having to translate a possible error code.

End-Point Names

By design, RESTful end-points are intended to act on a resource or a collection of resources. As a result, end-point names should always represent a noun. In the example above, the focus was on the customer or customers.

A common misunderstanding is to create end-points that are really verbs, like perhaps a process_invoice end-point. While this approach is popular in a Remote Procedure Call (RPC), RESTful web-services should not leave any side effects from an HTTP method call.

Documentation

Even if you are developing your RESTful API for internal use only, it is a good idea to include documentation as part of the development effort. Products like Swagger or MireDot provide an easy way to document your end-points by use of JavaDocs and Annotations. The documentation can be added to your build process, making life easier for other developers on your team. In fact, my own documentation has helped me when I look back at updates which were completed several sprints in the past.

Unit Testing

Like all object oriented classes and methods, unit testing should always be a priority. With Java, the most common unit test framework is JUnit, which I recommend using testing your RESTful API end-points.

Versioning

Versioning of the RESTful API end-point has also received a lot of discussion lately. A common rule of thumb suggests that ...

If you do not need to implement versioning in your API, don't add it merely for the sake of adding it.

However, in cases where you must include versioning, I recommend implementing the latest API version under a versionless API base URI. In the example above, the most recent version for the customers list would be similar to what is listed below:

http://myhost/api/customers

If I had a need to include versioning and my current version was at API version 2.0, the following aliases would also be valid for the URI above:

http://myhost/api/v2.0/customers
http://myhost/api/v2/customers

However, calling any of the URI's listed below would result in prior versions of the API:

http://myhost/api/v1/customers
http://myhost/api/v1.7/customers

Keep in mind, it can be a lot of work to maintain multiple versions of a given end-point, which is why the recommendation is to only use versioning if you have a valid reason to do so.

Conclusion

RESTful end-points lead the industry consuming a landslide majority over all other competitors combined. This popularity has caused RESTful end-points to enter corporate environments as well. The key is to make sure your RESTful API is doing everything it should be doing by following the suggestions provided in this article.

I intentionally did not talk about RESTful API security, since that is an entire topic on it's own. Perhaps even a topic I will talk about in the near future.