W3907 REST

From Coder Merlin
Within these castle walls be forged Mavens of Computer Science ...
— Merlin, The Coder


Introduction[edit]

In software development, REST APIs are a common form of software architecture that 99 percent of developers will encounter. APIs are among the most important in terms of making software work at a conceptual level, especially on 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 this experience, 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 go over exactly what APIs are. APIs are specific parts of an application that are exposed to other software applications. This is why they are called Application Programming Interfaces: 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 do 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". We call these two computers the client and the server. The client can use the REST API to make specific requests to a server, and the server responds 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, and the customers can be thought of as the clients. 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 cannot request something that is not on the menu in the same way that a client cannot 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 front-end, what the clients can actually see, and then you'd have the back-end, the parts that the client can't see such as your database. The client will likely have an Upload button so they can select and upload the image they want stored on the database.

When the client clicks the Upload button, the front-end sends a request to the back-end, sending the image data with it. The back-end sends a response, sending a status message stating that the image was uploaded to the database. This represents an API between an application's front-end and its back-end; however, APIs are even more common than this.

Simply navigating to a website is interacting with an API. When you go to any website, you are making a Get request to a server for a Web page, and the server responds with that 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 it responds 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]

1 What does a REST API enable?

The server to freely send resources to the client software
A client to use the server as an extension of itself
Two software components—the client and the server—to communicate in a specific way via requests and responses
A client to use the server in whatever way it likes

2 True or False: REST APIs are standardized in part for scaling purposes.

True
False

3 True or False: REST APIs expose the entirety of the server's software.

True
False

4 True or False: REST APIs are invoked when visiting a website.

True
False


REST API Architecture[edit]

Now that you understand 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 go over Endpoints. An endpoint is simply one end of communication with an API. This is often a server represented by a URL such as the following:

https://example.com/path

Here, 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 operations on a path, these are Get, Post, Put, and Delete. As an example, think back to our API that uploaded images to a database. For that API to be a REST API, it must 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 interact only with whatever the API exposes.

Quiz[edit]

1 What operations need to be handled for an API to be RESTful?

Create, Read, Update, Delete
Get, Post, Put, Delete
Memory Allocation, Loops, If Statements, Variable Declaration
All APIs are RESTful

2 What could be an issue if REST APIs are not made to be secure?

The client might not get the intended response
Critical data of the server could be exposed
The server would be unable to handle all the requests because of memory issues
The API would not be able to handle all the client calls

3 What are endpoints?

URLs
Computers
The two ends of communication of a given API call
All the software and hardware that was involved in an API call


Status Codes and Middleware[edit]

Often, when it comes to APIs, several steps 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 an 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, it receives a response depending on the type of request it 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, characterized by number ranges: 200s, 400s, and 500s.

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, thus indicating that the desired item was created.

A Status Code in the 400s means that something was wrong with the request. This is where the famous 404, not found, error comes from. You can try this yourself by typing a nonsensical 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 indicate that something was wrong the server itself, stating that something went wrong internally. The request was fine but something, whether in the middleware or some other portion of the code base, went wrong.

Quiz[edit]

1 What is the purpose of a Status Code?

To reflect the outcome of an API call, and, if something failed, determine where the issue arose
To serialize the API calls made by an application
To sort API calls into tiers (200s, 400s, and 500s) based on their level of efficiency
To tell the developer how much traffic a certain API call is getting

2 Which of the following is an area where Middleware can be used?

Parsing data given in the request
Adding a record to a database using the data from a Post request
All of the above
None of the above

3 True or False: Specific Status Codes are given for not found errors and successful creation of a resource.

True
False


Interacting with a REST API[edit]

As 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 front-end such as a button click.

In terms of creating a REST API, you would likely need to use a tool such as NodeJS, although you can use just about any programming language. Depending on the language, there will be different tools and frameworks available to create a REST API such as Express for NodeJS.

Key Concepts[edit]

Key ConceptsKeyConceptsIcon.png
  • 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 the software on either end
  • 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 sends 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 respond with Status Codes: 200s indicate success, 400s indicate bad requests, and 500s indicate errors in the server

References[edit]