Web APIs are often the best way to go when different parts of your application need to communicate, or when people outside of your organization need to communicate with your application. Not only are web apis based upon a widely understood and implemented protocol, but they are also widely accepted across industry. Further, if your API is structured properly, using HTTP enables developers using a wide variety of platforms and languages to easily interact with it.
However, there is always a price to wide acceptance and easy use. Usually, that price is that there are expectations to how your system will behave, expectations both obvious and surprising. This is the case with building a REST API. While many concepts are fairly obvious and easily understood, their implications can occasionally be surprising.
Before we get into the episode a little review of REST. Representational State Transfer, which is an architectural style for communications between systems on the web. REST systems are characterized by statelessness and separation of the concerns of the client and the server. Defined as request/response between the client and the server.
Many apps have one or more components that are exposed through a RESTful API. If you do this well and make it easy to work with your API, people will find it easier to start connecting to your system. This is one of the best ways to get and keep larger clients, as most companies are far more hesitant to disconnect from automated systems than they might from manual ones. Building your API using REST best practices will reduce the friction for these clients.

Episode Breakdown

Improper Use of Response Codes
There are known response codes for various states of the server. Use them. Another common mistake is to create redirect loops accidentally. It’s very common to see incorrect response codes (for instance, returning a 200 along with an error message).


* Informational responses (100-199) – Notables => 101: Switching protocol
* Success responses (200-299) – 200: Ok, 204: No content
* Redirects (300-399) – 301: Moved Permanently
* Client Errors (400-499) – 401: Unauthorized, 404: Not found, 403: Forbidden
* Server Errors (500-599) – 500 -Internal Server error

Improper Use of HTTP Verbs
Typical mistakes in this area include using the wrong verb for the intent of your action. This would be things like using a GET to make changes to the system or POST to retrieve something.


* Get – Gets things from the server.
* Head – Identical to a get, but doesn’t get the body.
* Post – Submits an entity to the resource.
* Put – Replaces a resource.
* Delete – Deletes a resource.
* Patch – Applies partial modifications to a resource.

Incorrect use MIME types
The client is responsible for specifying what type of content they want and they negotiate that with the server. A common failure is when this doesn’t happen. Another common mistake is to completely ignore the content type requested, or to send content back that doesn’t have the mime type set (sending json back as text, for instance).

* text/plain is exactly what it sounds like, raw text.
* text/html is also exactly what it sounds like, html for use in a browser.
* application/json is pretty common as well as stands for javascript object notation, which is serialization format.
* application/x-www-form-urlencoded sends the body of an HTTP message as one large string with name/value pairs separated by the ampersand.
* multipart/form-data sends name/value pairs as separate parts of the message separated by a string boundary.

Incorrect use of Caching