W3907 REST
Introduction[edit]
Within Software Development, REST APIs are a common form of software architecture that 99% of Developers will encounter. APIs are among the most important in terms of making software work at a conceptual level especially within the Web. REST API stands for Representational State Transfer Application Programming Interface [1]. Essentially, these are software interfaces that follow a set architecture to integrate applications. Said another way, REST APIs are APIs that follow a specific procedure that makes them RESTful. In the following, we'll dive into what these terms actually mean, how they're used, and we'll finish by talking about how you can work with a REST API
Meaning of REST and APIs[edit]
To start, let's understand exactly what are APIs. APIs are specific parts of an Application that are exposed to other software applications. This is why they are called Application Programming Interface: APIs allow applications to interface with each other in specific ways.
REST APIs are the most common types of APIs that use the RESTful characteristics which are simply a set of architectural instructions that standardize APIs to scale and not need the state of either application using the API.
The best way to think of REST APIs is that they are a standardized way of communicating between two Applications. Therefore, REST APIs are a means of communication between two "computers" these two computers we call the client and the server. The client can use the REST API to make specific Requests to a Server, and the Server will Respond in a specific way.
Non-technical Example[edit]
One of the most common examples used to understand REST APIs is a Restaurant. A Restaurant can be thought of as the Server while the customers can be thought of as the Client. The Menu, therefore, is the API. This is because the Menu (API) tells the customers (Client) how they are able to interact with the Restaurant (Server). The customer can not request something that is not on the Menu in the same way that a Client can not request something from the Server that is not exposed through the API.
Technical Example[edit]
Now imagine you have a Web Application where a Client can upload images onto a Database. Your Web Application will be composed of many components. For one, you'd have the Frontend, what the Clients can actually see, and then you'd have the backend, the parts that the Client can't see such as your database. The Client will likely have an upload button where they can select and upload the image they'd like to be stored on the database.
When the client presses the upload button, the Frontend will send a Request to the Backend, sending the image data with it, and the Backend will send a Response, sending a status message stating that the image was uploaded onto the database. This represents an API between an Application's Frontend and its Backend, however APIs are even more common than this.
Simply navigating to a website is interacting with an API. You see, when you go to any website, you are making a Get Request to some server for a web page and the server will respond with that specific web page. This is what people are referring to when they have their websites hosted on a cloud platform such as AWS or Google Cloud. Their Web Page is held on one of their servers and will respond to any requests to that url.
So as you can see, REST APIs are truly everywhere and are integral to how applications interact with each other
Quiz[edit]
REST API Architecture[edit]
Having understood what exactly REST APIs do, let's take a closer look at how they do this and the actual architecture that stands behind them. First, let's understand Endpoints.An Endpoint is simply one end of communication with an API, this will often be a server represented by a url such as the following.
https://example.com/pathHere, the server is hosted on example.com and we can access specific parts of the server with the path. For an API, we should be able to perform four specific operations on a given path, these are Get, Post, Put, and Delete. To give you an example, think back to our API that uploaded images onto a Database. For that API to be a REST API, it will need to be able to Get Images from the database, Post Images onto the the database, Put (Update) Images on the database, and Delete Images from the database.
In this way, the Client can use just the REST API to interact with specific data. Keep in mind that REST APIs need to be made securely and made so that the Client can only interact with whatever the API exposes.
Quiz[edit]
Status Codes and Middleware[edit]
Often, when it comes to APIs, there are steps that need to be taken in between the Request and Response. This is what is known as Middleware. It can essentially be thought of as what needs to be done after getting a Request and sending the Response. This can be anything from parsing data to performing logic on a given input.
Often you can see Middleware with POST and PUT requests as somewhere in between the Request and the Response, there needs to be the actual action of Creating or Updating whatever it is based on the input from the Request.
Additionally, when the Client makes a Request, they will receive a Response depending on the type of Request they made (Get, Post, Put, Delete), but regardless of the sort of request, the Response will always contain a Status Code. Status Codes indicate how the Request was handled, and there are three main types.
A Status Code in the 200s means that the Request was a success and the API did what was requested of it. Specifically, the code 201 is used in the Response to Post Requests, specifically indicating that the desired item was Created. However, a Status Code in the 400s means that there was something wrong with the Request that was made.
This is where the famous 404 not found error comes from. You can try this yourself by typing a non-sensical path to a random website such as Coder Merlin, it should respond with a 404 not found error. This is because you are making a GET Request to a specific part of the website's server however the API responds with a 404 because the Request you made was flawed and it couldn't find that resource on the Server.
By contrast, Status Codes in the 500s puts the blame on the Server itself, stating that something went wrong internally. The Request was fine but something, whether it be in the middleware or some other portion of the codebase, went wrong.
Quiz[edit]
Interacting with a REST API[edit]
As we mentioned, simply navigating the web requires making Requests via REST APIs, but interacting with REST APIs as a Software Developer is a little more interesting. In most contexts, you'll find REST APIs in the Web and usually made with Javascript. Keep in mind, however, that many languages can be used to make REST APIs.
In terms of interacting with a REST API in the context of a web application, there are many resources to make the standard Requests such as fetch or Axios [2]. If you're making a Web Application, you would simply use one of the many resources to make a call to the appropriate REST API upon certain actions in the Frontend such as a button click.
In terms of creating a REST API, you would likely need to use a tool such as NodeJS though you can use just about any programming language. Depending on the language, there will be different tools and frameworks available to create a given REST API such as Express for NodeJS.
Key Concepts[edit]
- APIs allow Software to Interface with each other in specific ways
- RESTful Characteristics are a standardization on top of an API that allow APIs to Scale and not require the state of either Software that Interface
- Endpoints simply refer to the ends of the REST API Communication where the Server is simply referenced with a url
- The Client can use a REST API to make a defined set of Requests to the Server and the Server will send a Response accordingly
- For an API to be RESTful, it needs to handle GET, POST, PUT, and DELETE requests, often requiring Middleware in between Requests and Responses
- Servers will respond with Status Codes: 200s indicate success, 400s indicate bad requests and 500s indicate errors in the Server
