Web Services, APIs, and REST

In this article, I’m going to talk about APIs, REST, RESTful Web Services and everything you need to know about this topic.

Let’s talk about APIs first. In this section, I’ll give a brief overview of what an API is, and how it fits into the big picture. I’m going to answer three questions; What is API? How does it relate to web services? And what is a REST API? Okay, let’s start by answering the first question. API stands for Application Programming Interface, and it is a way to let software components talk to each other. This simple diagram shows a visualization of this communication.

Let’s start by a simple analogy. I’m assuming you’re familiar with object-oriented programming. In object-oriented programming, objects have methods and attributes. Later, when we want to use or communicate with the objects to use its attributes or its functionalities, we use the methods and the attributes that the object exposes. Here, we have an object called ‘objectA,’ and it has two attributes and two methods.

The set of these methods and attributes is called the API of the object. To communicate or use the functionalities of object, we do that through its API. So basically, an API is just a way to communicate with software components. It could be anything in any form. The only thing that it has to be is that it has to be a way to communicate with software components. In the previous example, I took the form of a set of attributes and methods. Now, let me give you another example everyone knows about. API is the way we interact with the operating system in the command line. Actually, this is a form of using an API. If you are Mac or Linux or Windows user, you may be familiar with the terminal or the command-line interface. You could write a script that uses the same API that is exposed by the system to shut it down or do any of the operations that are permissible by the system. So, an API could be anything in any form.

Alright, let’s answer the second question; how does the concept of an API relate to web services? And what is the difference between them? We almost always hear web services and API used interchangeably, and this causes a lot of confusion even for experienced developers. We often hear REST web services and APIs. Well, are they the same? I hope this article will clear things up. Remember what we said about an API, it is just a way to communicate with the software components. Most of the times, if not all, APIs are created for other software components. How an API is implemented and what it consists of is not important. To sum up, API could be anything in any form. The only thing that it has to be is that it has to be a way to communicate with a software component.

Web services are a set of rules and technologies that enable two or more components on the web to talk to each other. So, if you think about it, web services are just API, right? Just as the example of the object-oriented programming, the set of methods and attributes of an object are called an API in the object-oriented context. Similarly, web services are APIs in the context of the web. So, on the web, an API and a web service are the same thing. But in general, not every API is the web service. Next time when you may hear REST API or REST Web Service, they are basically the same thing.

It’s time to answer the third and last question. What is the REST API, in other words, what is the REST Web Service? REST API is an API that follows the rules of the REST specification. That’s all you need to know right now. When we talk about REST architecture and rules in the next sections, you will understand, what the REST API really is. Now, before I continue, I want to make sure you understand the rules part.

A web service has to follow some rules. More specifically, how we are going to talk to the other software component? What will send and what will receive? And how all of that is going to be handled? This is what we mean by rules? We could have an API that doesn’t necessarily follow the REST rules. So, a REST API follows the REST rules.

Now, let’s talk about REST, Representational State Transfer. Instead of directly defining exactly what REST is, let me answer some important questions and that first will help you put the REST pieces to the right places in the big picture, second, you will know the answer of the two questions. With that, we will hit two birds with just one stone.

Alright, let’s see the first question. How does HTTP relate to REST? We all know that HTTP is an application layer protocol for sending and receiving messages over a network. As developers, we can use the HTTP protocol in any way we want. We could, for instance, build a server and the client that use only the GET method for all kinds of interactions. If you know the HTTP protocol very well, you will know that you can do that. On the other hand, REST is a specification that dictates how distributed systems on the web should communicate. We must follow certain rules that restrict the use of the HTTP method. So, the answer to the question what the relationship between REST and HTTP is, REST is a certain way to implement HTTP communication.

How does The WEB relate to REST? That’s a really great question. REST is a concept invented by Roy Fielding. REST is not something new, actually, it is as old as the web. REST is how communication on the web is supposed to work. Of course, that guy added a lot of stuff and give us best practices. He did a lot of great things, but REST is the underlying architecture of the WEB. This means that developers broke the rules. If you look into web services that are built in the past and some of the new ones, you’ll see a lot of violation of these rules. For example, REST says when you want to send something to a component on the web such as a service that post data to a database, REST says we should use the POST HTTP method. But that’s not what all developers do. Some actually, use just the GET method for all operations. I know some developers will hate me if they hear this, because developers don’t want to be restricted. However, REST is not about restriction. REST is about doing things how they’re supposed to be. By the way, I’m not saying REST is the best architectural style, but it’s still better than doing things arbitrarily.

Now, let’s define exactly what REST is and list some of its rules. And if you want to dive deeper, I highly recommend checking the source Roy Fielding’s dissertation. To define the REST there is no better way than hearing the definition from its inventor. “Throughout the HTTP standardization process, I was called on to defend the design choices of the Web. That is an extremely difficult thing to do with in a process that accepts proposals from anyone on a topic that was rapidly becoming the center of an entire industry. I had comments from well over 500 developers, many of whom were distinguished engineers with decades of experience, and I had to explain everything from the most abstract notions of Web interaction to the finest details of HTTP syntax. That process honed my model down to a core set of principles, properties, and constraints that are now called REST”. To put it simply, REST is just a way of communication between components on the web.

For now, all you need to know is that there are two most important rules. These two rules are what most APIs need, and they are actually the answers of the two questions that every API should answer. Well, what are these questions? The first question is how to tell the service provider which operation the client wants to perform. Let’s call it the Method Information, okay? The second question is how to tell the service provider what data the client wants to operate on and call it the Scoping Information. So, these are the two questions that every API should answer. Now, of course, there is more than an answer to each question, but if we want our API to be RESTful, we got to answer with the REST rules.

Let’s see how REST answers these questions. REST answers the first question like this; the method information should be expressed in the HTTP verb. That’s it. So, if you want to delete something, we don’t use the GET method. This is possible but it’s not even intuitive, right? So, we use the DELETE HTTP method instead.

There is difference between the two requests. The first one is not restful, the second one is restful. So, to tell the service provider which operation the client wants to perform that information should be expressed in the HTTP verb. And the service provider when it receives the request it will open it and go look for the operation it needs to perform on the HTTP verb, not somewhere else.

The second question which is what data the client should operate on or the scoping information as we called it. REST answers this question like this; the scoping information should go in the URI. If you are not familiar with URIs, URNs, URLs, and the difference between them, you can visit my previous post about them. Another thing to note here, in REST, everything that a client can operate on is called their resource. And its resource is identifiable by a unique URI. Here in the illustration, the scoping information is a parameter in the URI.

Lastly, how a RESTful API works? We had enough talk, and I hope you have a good idea about all of this. Now, let’s see some action. I think things are about to become clearer now. I’ll show you how a RESTful API works in a typical service provider client communication using a diagram. So, REST API communication is just a typical HTTP communication that follows the REST principles and is restricted by the REST rules. The first thing to note is that REST APIs use HTTP methods suitably. Meaning that each operation is requested by using the appropriate HTTP method; GET for getting data, POST for creating, DELETE for deleting and etc. The second thing is that REST API specifies scoping information in the parameters or in static portions of the URI. Of course, as we’ve seen before, REST API uses common data formats for exchanging data like XML and JSON. JSON is the most common data format in REST communication. The last thing I want to note here is that REST communications are stateless meaning that the server doesn’t maintain the states of its clients.

Here as you can see from the diagram, it’s just a typical request/response cycle. We have service provider and the service consumer. First, the service consumer or the client sends the requests specifying the operation in the HTTP method and the resource it wants to operate on in the URI. If it’s a POST or PUT request, it will contain a body. Then, the service provider receives requests, opens it, analyzes it, does some operations, and sends back the response. That’s it!

I hope I managed to give you a clear and solid idea about REST API, and I hope you enjoyed this article. Before you go, let me tell you something. So, I will list several thing of what you should know in order to start building relatively complex REST API. First, you have to have a solid understanding of HTTP methods, headers and other stuffs. Second, you must be familiar with data exchange formats like JSON and XML. And last thing is that it would be great if you know about REST rules and understand the REST concepts. This is it!