What is a Restful API?

What is an API

There are a lot of misconceptions about APIs out there but understanding them at a high-level is easier than it may seem. Working with APIs is an integral part of modern software development, so let’s break down APIs conceptually and give an overview of what they are and how they are utilized. 

First, let’s address the acronym itself. An API is short for  Application Programming Interface. It is a protocol or interface definition for software programs to communicate with each other. 

Some examples of this are client apps (a web application or mobile application, for example) communicating with an app server, server to server communication, or a custom application communicating with third-party libraries.

One common misconception is that APIs require the internet. They actually do not. An example of an API that does not require the internet is the Java API. For those not familiar, Java is a programming language. The Java API is simply the base library of all the different functions offered by the Java language. The designers of Java wrote a software program that you can communicate with in a standard way in your application that uses the Java programming language. 

Any sort of package that you might install in your project, whether it’s a React Native app, a Swift app, or a Node.js app has a package manager where you can download code that somebody else has written. Those packages are in a sense, APIs. They are a set of code that you are communicating with from your app that you are writing. 

So, in short, APIs are just a way of multiple pieces of software communicating with each other. 

What is a REST API

If an API is just a means of softwares communicating with each other, then REST is a standard built on top of that to standardize an API.  REST is short for Representational State Transfer. At a high level, REST is how you interact with APIs in terms of data representations. The API itself is a layer for transferring or communicating that state between the different pieces of software. 

In the early 2000’s when the internet was really taking off and people were beginning to share code, it became the Wild West! Everyone was building APIs in their own way. There was no standardization, so you had to essentially relearn the standards of each API you wanted to use. Roy Fielding, a PHD student from University of California, Irvine, came up with the standard that we now call REST. Roy solved the problem described above and defined rules around how you might build an API, so that from API to API you’re not having to learn different concepts. You’re applying the same concepts and getting the benefits of reuse no matter who wrote the code or what purpose the code serves. 

The 6 principles of REST

• Uniform Interface
• Client-Server
• Stateless
• Cacheable
• Layered System
• Code-on-Demand

Uniform Interface is the most complicated of the 6 principles. Across all your different resources, your means of retrieving data and sending data to the API is going to look and feel the same. You’re not going to change up the function calls or the methods that are available for each different resource. You are instead going to try your best to write the code in a standardized way across the API. REST, as a standard, does not define what that interface is. It does not tell you what functions you need to offer or not offer; all it says is that you need to be consistent when you come up with what your standard is for your API. 

Below are some sub definitions for creating your API. 

• Resources uniquely identified – Each resource type gets a unique (and hopefully self-explanatory) name.

• Resources manipulated through representations – A “representation” is just the middleman format used, such as JSON or XML. Messages are self-descriptive. All the information needed to interpret the message are contained in the message itself (think of the content-type header in HTTP).

• Hypermedia as the engine of application state – This one is tricky. The explanation on the REST API website is slightly misleading, suggesting that you only need the base URI of the API with no additional documentation as an entry point to begin using the API. It’s saying that URIs map to particular resources. In other words, a particular URI is associated with a particular data state (i.e. resource).

Client Server is really about enforcing separation of concerns. REST API is really about data, not about the user interface and the actual elements on screen you interact with. This is another slightly misleading point that would suggest REST APIs have to be on the internet. They don’t. When you’re designing a REST API, all you need to be concerned about is the raw data itself, not the user interface. 

REST APIs are Stateless. This is huge! They have no state in and of themselves. Being stateless means that the API does not maintain a session between each call you make.

• Each request contains all the necessary information it needs, and the server does not maintain any state between requests.
• E.g. Authentication header included in every request, rather than issuing an initial “login” authentication request which the API then maintains in state for future requests. 

The API does not remember who you are. Every request is completely standalone, and with every request that you send you must include all the necessary information to complete that request, including authorization headers. A common misconception about REST APIs is that authorization is one of the standards, but it is not. Whenever you decide to stack on extra layers, like authentication, they need to work independently. 

The next principle is the data should be Cacheable. This is simply to try to save on bandwidth. 

• Resources should explicitly mark themselves as cacheable or not.
• As much as possible, resources should be cacheable to cut down on unnecessary requests.
  • Reduce latency
  • Reduce bandwidth
  • Reduce load on servers
  • Reduce risk of failed requests

REST APIs are Layered, which really comes down to how you organize the relationships between your data, which is hierarchical in nature. Using Facebook as an example, Users have many posts and posts have many comments. Those are relationships with each other, but there is a hierarchy where the user owns the posts, and the posts own the comments. That concept can be abstracted into any app you build.

The final principle is Code on Demand, which Mr. Fielding marked as “optional”.  If your API adheres to the first 5 principles, it is Restful. The idea of Code on Demand is that the server can deliver code to the client (web app, mobile app or whatever it is that is consuming the data) that the client itself can then turn around and run against the API. This may seem like a bizarre concept, but remember this was being developed in the early 2000’s. Some would argue this sixth principle is outdated in the modern world. We are now using our own systems we have developed for interacting with APIs, and it could potentially be a security risk if the API and client are both not owned by the same party. Even if this principle no longer applies to the way we write apps today, it still makes a good point about what REST is trying to accomplish, which is saving you work on the front end by standardizing the means by which you communicate with the API. 

To RECAP! 

Rest is not … 

• Any web API
• HTTP
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
• An authentication protocol
• Exclusively JSON data

Rest is…

• Any API (web or otherwise) which adheres to certain standards.
• That’s it.

Now, let’s design a Restful API! 

How about a simple Blog?

Step 1 : Define Resources

• Users
• Articles
• Comments

Step 2 : Define Resource Attributes

• Users
  • Id
  • username
  • password
• Articles
  • Id
  • content
  • user id
• Comments
  • id
  • article id
  • user id
  • content

Step 3 : Define Resource Access 

• Users
  • GET /users
  • POST /users
  • GET /users/{id}
  • PUT /users/{id}
  • DELETE /users/{id}
• Article
  • GET /articles
  • GET /users/{id}/articles
  • POST /articles
  • GET /articles/{id}
  • PUT/articles/{id}
  • DELETE /articles/{id}
• Comments
  • GET /articles/{id}/comments
  • POST /comments
  • GET /comments/{id}
  • PUT /comments/{id}
  • DELETE /comments/{id}

And lastly, PATTERNS TO AVOID. 

• Posts
  • POST /users/{id}/articles
  • GET /users/{id}/articles/{id}
  • PUT /users/{id}/articles/{id}
  • DELETE /users/{id}/articles/{id}
• Comments
  • POST /users/{id}/articles/{id}/comments
  • GET /users/{id}/articles/{id}/comments
  • POST /posts/{id}/comments/
  • GET /posts/{id}/comments/{id}
  • etc.

RESTFUL APIs have increased the productivity of the developers worldwide by making it easy for them to display the information on the client-side and store or manipulate the data on the server-side. For more helpful tips and insight to strengthen your development knowledge, visit us at www.TyrannosaurusTech.com.