In this lesson, I’m going to introduce you to an architectural style for building Web APIs called: REST. Let’s establish a few terms before getting started. Specifically, I want to ensure that we’re using a shared understanding of the terms API and web API. 

The term API stands for application programming interface. And it’s exactly what it sounds like. It’s a form of interface used to programmatically interact with an application. There are different types of APIs. We’ll be focusing on web-based APIs in this lesson. 

A web API refers to an API which is based on web protocols such as HTTP and HTTPS. Going forward I’ll refer to HTTP generically to imply either or both HTTP and HTTPS. Unless the distinction is relevant. Web APIs are used to interact with web-based applications. Many different companies provide web APIs as a means of interacting with their services programmatically. For example, twitter, slack, NASA, amazon, and basically every other company in the world provide web APIs.

Web APIs allow client applications to interact with server-side applications. Browser-based and mobile applications are examples of client-server applications. Where a client sends requests via HTTP and receives responses containing the requested data from the server. Because a REST API is just a specific type of web API, I want to start out by visualizing a web API so that you’ll have something to compare with REST APIs.

Imagine a pet adoption website that allows users to search for pets in their area. When a user enters their location and clicks search the browser runs some javascript which sends a GET request to a web API. Server-side applications are responsible for defining the structure of web APIs. A web API defines the interface between a client and server application. It specifies which actions are possible and how to perform them. 

This example demonstrates a web API for finding pets in a given location. The name locate-pets in the URL path tells the server which action to perform. The URL query parameter specifies the location to search within. The server-side application receives the request and breaks down the URL to understand what to do next. It maps the path to the responsible code, which searches the provided location and responds with a list of pets in the given area. 

In this example, the returned data is in JSON format. JSON is one of the most common data formats used for web APIs. Though web APIs can return other data types such as html, videos, images, etc. Now that you’ve seen a basic example of a web API let’s talk about REST APIs. A REST API is a specific type of web API. REST was first introduced in 2000 as a PhD thesis by Roy Fielding. 

REST stands for representational state transfer. It’s an architectural style which transfers a representation of information between a client and server application. The representation specifies the current state of the information being transferred. 

Clients can perform actions which allow them to view and change the state of information on the server. This is a rather abstract way to talk about REST APIs so let’s explore them further.

During the time period when REST was first introduced, web technologies were quickly growing and evolving. Web applications were becoming the most common form of user-facing application. And web APIs were connecting all of these different applications and services. 

With these technologies being relatively new there just wasn’t enough understanding of how to build web APIs meant for long-term use. Many of the APIs at that time followed their own path for defining data structures and communication mechanisms. 

Building and maintaining long-term applications introduces many challenges which might not exist otherwise. Supporting applications over long periods of time is difficult. Considerations have to be made regarding how to build a system which can evolve over time; without system disruption or a massive investment in development hours. 

At the time the lack of API standardization resulted in software which was difficult to build and maintain at scale. Every API was at least just different enough to require developers to pore over documentation, trying to learn the intricacies of each API. 

REST is an API architectural style which was proposed as a means of providing a standardized interface for client-server applications. REST defines a means of communication and data representation. 

REST introduced some new concepts used to form a more generic means of communicating and representing information with an API. It also introduced a series of software architectural constraints which when applied, allow an API to be considered: RESTful. This has become a common industry term to indicate that a web API adheres to the REST architecture.

REST is based on the notion of representing data in the form of resources. A resource is any concept which can be modeled using some representation. For example articles, images, videos, pets, employees, etc. Resources are typically represented by nouns: people, places, things, etc. 

REST considers all data to be equal in the form of resources. A resource is an abstraction for data. Different concepts can be represented in different ways using different resource types. For example an employee might be represented as a JSON document; where an image is represented as an image file. Each resource is represented by an identifier which can be used to locate a given resource. Resources are identified using a URI. URIs are a concept independent of REST.

URIs use a generic syntax for representing resources used in different contexts. The generic syntax allows engineers to build on top of the URI structure to create schemas used for representing different types of resources. For example, a URL is a specific type of URI. Which is why URLs are commonly used as URIs for REST APIs. REST APIs define a series of interconnected resources which all use the same generic interface for performing operations. This is a key aspect of REST. Resources are standardized units of data; regardless of the concept being represented. 

Actions can be performed on resources. Actions such as creating, reading, updating, and deleting. It doesn’t matter if a resource is a file or a record in a database. From the perspective of the API they’re all just resources. REST APIs are designed around six architectural constraints which will be covered in part 2 of this lesson. So, when you’re ready to keep learning, I’ll see you in the next lesson.