What is REST API & RESTful Web Services

REST stands for REpresentational State Transfer and RESTful web services are applications that implement REST architecture. Some of the questions that might come up when you first try to understand REST are: What is being represented? What is a state? And what is being transferred?


The word Representational means there is a transfer of "representations of resources". The resources can be pretty much anything that can be named on the web like: user, list of users, photo, list of photos, comments, posts, articles, page, video, book, profile etc....

To understand, how exactly we get "representations of resources", let's look at how everyone interacts with web pages via client-server model and the HTTP protocol.

The first important point to understand is, every time you type a URL in a browser or click on a web page link, you are sending a "request" for a resource from a web server, and the web server "responds" and delivers the requested resource to your browser.

Representations of Resources

The second important point is that the web server doesn't deliver the actual resource, but rather, a "representation" of a resource in a format that is readable (eg: HTML, IMAGE). Think of actual resource as physical things located either in a Web Server database or stored on the Web Server hard drive, and "representations" of those resources as copies in either a readable format for a human being (html, image) or easy to work with format for programmers (json, xml).

It's also helpful to think of the whole web as a bunch of resources, remember that we always request a resource when clicking on a link or typing a URL, no wonder the URL stands for Uniform Resource Locator. Let's take a closer look at the URL now.

If you click on this link: https://clevertechie.com/img/logov2dark.png you will be requesting the logov2dark.png clever techie image logo resource from the web server where the physical file is located (actual resource). The web server is going to respond with a representation of that resource in a image format.

You can also see this logo image on every page of clevertechie.com web site, represented in HTML format. In fact, when the home page of https://clevertechie.com is loaded, you are presented with multiple resources on the same page (logo image, multiple thumbnail images, category names) as well as links which lead to other resources.


To continue from the clever techie example above, think of clevertechie.com as one application. When the home page first loads, you get one "state" of the application, a home page with links to other resources. When you click on any of those "resources", you get transitioned into the next "state" of the application, which could be a single page with a tutorial or guide link this one. This is what is meant by the word "state", it's the state of the application on a client machine and the state changes every time you click on a link to request a new resource.


When the resource gets "transferred" from Web Server to Client we get a representation of the resource in whatever format the resource is presented. This is what is meant by the word transfer, however it can also refer to the transfer of the application state when we click on the next link and get "transferred" to another page. At this point, understanding how REST works should be easy.

HTTP Verbs

Notice the verbs: GET, POST, PUT, DELETE. Of course, we don't ever type those in the browser, those are just methods or actions that describe what kind of HTTP request we're sending to the web server. For example "GET" is the most common one and you can think of it as "consume" or "read" information, every time you click on a link on a web page, most of the time, you're sending a GET request.

POST is often used to submit information, every time you sign up for a newsletter, login with your user and password or send a tweet, you're sending a POST HTTP request.

That's pretty much it for REST, to summarize, we send a request for a resource via HTTP protocol, the resource is identified by the URL ( Uniform Resource Locator ), the web server responds with a representation of that resource in a format that we can work with. The application state changes when you click on a link or type another URL on a web page and you get transferred new representations of other resources.


Now that we understand how REST architecture works, we're ready to understand REST API. API stands for Application Programming Interface, I like to simplify it by saying API is just a bunch of useful methods/functions for us, programmers, to use.

Now our request is made up of "REST API endpoint URL", API method and parameter, let's take a closer look at each.

REST API endpoint URL and Methods

The REST API endpoint URL is API resource location, notice that when a web application provides the REST API, the API itself is a resource. Like I mentioned earlier, you can think of the API as a bunch of useful methods. Given that, we select from a list of available methods from the API (which is listed in the web application API documentation) and put that method inside of our URL.


Just like functions and methods have parameters that can be passed to them in programming languages, REST API methods have a list of parameters which we can pass to them to get what we want out of our request. So we pass on the parameters to the methods to complete our REST API request at the end of our URL. All the parameters which can be used with methods will also be listed in the API documentation.

You can check out https://www.flickr.com/services/api/ for a sample API documentation which lists all the methods along with the parameters.

REST API Response

The response that we get back from the REST API, may look like gibberish to a human being, that's because it's not meant to read by human beings, but rather other applications, and the format (JSON, XML) makes it easier for, us programmers, to read and parse the response using the code from within our own applications.

Below is a sample JSON response from using flickr.photos.search method. We get information about the photo we searched for like photo id, owner, secret key, title and other information.

{"id":"32728520582", "owner":"151443588@N08", "secret":"09e1eaff33", "server":"2930", "farm":3, "title":"Flowers", "ispublic":1, "isfriend":0, "isfamily":0}


I hope this has given you a good understanding of what REST API is and how to use RESTful web services that provide REST API. If you're still confused about any points mentioned in this guide, please post the comments below and I will answer any questions you may have promptly, thanks for reading.