Time for some more REST

This week I have chosen to deepen my understanding of REST API. The article, “RESTful API Design Tips from Experience” by Peter Boyer, goes over good RESTful design practices. The article covers many topics, including some I do not have experience with but are still useful for a greater understanding overall.

The article proposes that the API should state its version in the URLs. The author suggests adding a prefix to all URLs to specify API version. This makes the eventuality of version updates easier to handle.

A simple tip mentioned in the article is the use of plurals. When designing endpoints, plurals should be used instead of the singular form. This is to avoid possible misunderstandings of what the endpoint is used for.

Example:             /orders/customers          VS           /order/customer

Another tip in the article is to use nesting for relationship filtering. From what I understand, it is better to have multiple path variables for filtering than the use of query strings. The example in the article is very clear on the tip. Following this advice will make your endpoints easier to read.

The author advises to keep your API as flat as possible. He suggests that creating and fetching data should have a longer resource path than updating and deleting data. I do not really understand why this is the case. My best guess is the shorter path reduces unnecessary processes.

The next tip I found interesting was the important, if not obvious, idea for pagination of results. When working with larger databases, requests can have thousands of results. Since it would be impossible to display all the data, it makes sense to partition the results into pages and return one page at a time. Pagination can also significantly reduce the expense of a request.

The last tip I will mention from the article is the usage of status codes.  HTTP status codes should be used consistently and properly. This means the status should use the proper code and provide additional details when necessary: an error code with a message of why the error occurred.

Overall, I found Boyer’s article to be very informative. I only mentioned a few of the topics raised in his article but all the topics are interesting and useful. Reading through this article gave me a better understanding of the nuances of RESTful API design and has helped me comprehend my current coursework (CS343) better. I suggest to anybody that is new to REST to read this article.

Article Referenced:

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create your website with WordPress.com
Get started
%d bloggers like this: