RESTful APIs and Server Responses
Introduction
APIs are software developers’ best friend. APIs, or application programming interfaces, help define how communication between different types of softwares should take place, and without them creating any sort of meaningful application would be virtually impossible. RESTful APIs, defined by Roy Fielding in his dissertation, take this importance a step further, as they define methods for applications to make HTTP requests to access data from servers. In this article, we’ll look at some of the inner-workings of RESTful APIs, including how servers respond upon receiving HTTP requests.
RESTful APIs
One important aspect of REST APIs and http requests are that the client and server must remain separate from one another. Users should not have any interaction with how data is stored behind the scenes, and this in turn also allows for the creation of better user interfaces. Another important part of RESTful APIs is that client requests should not rely on any information or state that is stored on the server to complete the request, but rather must contain all of the necessary information to complete the request in its body. The concept of idempotence is that some operations will always result in the same outcome. We can connect this with client requests because a duplicate client GET request to a server should always contain the same response. Because HTTP requests should not use any additional data from the server to be completed, this idea of idempotence holds true for many interactions we have between clients and servers. What exactly happens, though, when the server actually receives the request?
HTTP Requests
When a server receives an HTTP request, there are several steps that happen. Servers are expecting data to arrive in a specific manner, and if a request does not contain specific information it will send an error back to the user. Common errors include 40x errors (including the dreaded 404 error that most people have likely encountered before), and 400 level errors are returned when there is something wrong with the client’s request.
We can think of HTTP requests working similarly to how an online library system functions. It is possible to create searches that access the library’s database and return all books by a certain author or keyword. This is analogous to a GET request. We can request a book to check out, which will send information to the library, and is similar to a POST. And, if we’ve decided that we have chosen too many books to read, we can remove a book from our checkout list, much like a DELETE request would work.
What were to happen if we were requesting a book to checkout, but in the time that we were reading the book’s description, another user had reserved that same book? Let’s dive under the hood and explore how servers react to requests. In general, 200 level HTTP status codes represent successful requests, 300 level codes represent redirection, 400 level errors represent something wrong with the client request, and 500 level errors represent something wrong with the server.
Upon a successful search for a book in our online library website, we would likely get back a 200 OK message. Creating new resources in the server, such as when successfully completing a hold for a book, yields a 201 Created message. A common 300 level message is 301 Moved Permanently. This could happen if the library had a resource in the past, but the book was moved to a different branch.
400 level errors are a bit wider in scope. 401 Unauthorized messages result when authorization credentials are not present. Imagine not being logged in as a user but still requesting a book from the library. No bueno! 403 Forbidden requests happen when a user is authenticated but does not have permission for the particular resource. Think Harry Potter being a Hogwarts student and being able to access the library, but not any just book he pleased located in the restricted section (without permission from a professor). 404 Not Found errors happen when requesting unavailable resources. We can think back to our example here of requesting a book that has already been checked out, or books that were returned damaged and are currently being restored or repurchased and not currently available.
Conclusion
RESTful APIs are particularly useful to developers because they explain how to make requests for resources using HTTP methods, which is a vital piece of today’s computing. When servers receive client requests, they must interpret the request and try to access data to return to the client, or update or add information to the database if the client is making a POST or DELETE request. Servers then determine if the user has proper access to materials and then responds to requests accordingly.