What is a RESTful Web Service?

Confusing Web Dev Terminologies Broken Down — 2

Image for post
Image for post

There are two components to this popular phrase — “RESTful” and “Web Service”. Let’s talk about them one by one.

REST stands for representational state transfer. It is a software architectural style. An architectural style is not a thing by itself, instead it’s just a set of characteristics. Just like how “Gothic architecture” is a style, but a “Gothic cathedral” is a physical thing. Any software that follows the REST architectural style is said to be RESTful, hence the name “RESTful web service”.

The REST style allows for more effective communication between clients (code that handles user interaction and user interface) and servers (code that sends data to the client).

The most important feature of REST is that it enforces a uniform interface — a set of instructions that everyone follows. A client can send a request to a server at a specific URI (uniform resource identifier). The request usually consists of one of four operations: PUT (update data), GET (retrieve data), POST (create new data) and DELETE (delete data). Then the client can expect a response that’s is in a specific format. We’ll look at an example shortly.

With these agreed-upon URIs, operations and response formats, the client can treat the server as a black box, and vice versa. This means that the client doesn’t have to worry about how the server is implemented, it can just send a request and be confident that the server will do its job. Conversely, the server doesn’t care about the client’s implementation, it only listens to incoming requests.

This architecture brings much flexibility to developers because now clients and servers can be implemented separately. They can also be developed in any programming language, with any framework or library, as long as the software complies with the REST style.

A web service is a software that (1) provides functionalities for other software (2) over the web.

An example of a RESTful web service is the Github API. To get information about a Github user (e.g. my account, donfour), you can send a GET request to api.github.com/users/donfour(agreed-upon operation at an agreed-upon URI).

Github has a domain atapi.github.com. When the server receives a request at the route /users/, it knows that someone is requesting for user information. The server then reads the text that is after /users/ (in this case, donfour), looks up my data from the database, then return the data back to the client.

You can try it yourself! If you type in the URI in your browser, your browser will send a GET request to Github, and you will receive a response as follows:

{
"login": "donfour",
"id": 19992630,
"avatar_url": "https://avatars2.githubusercontent.com/u/19992630?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/donfour",
...more information
}

This data format (agreed-upon response format) is called JSON, short for JavaScript Object Notation. It’s obviously not very human-readable, but it’s perfect for computers. Computer code can extract information from JSON easily and further manipulate the data.

Let’s look at why Github API is a web service. It (1) provides functionalities (in this case, the functionality of looking up a user profile) to other software (2) over the web. Now, you can write code to do whatever you want with the retrieved data.

They often show up together and they can be confusing. In short, an API (application programming interface) refers to any methods that allow different software components to communicate with each other. A web service, on the other hand, is an API that works over the web.

So, web services are a subset of APIs. All Web services are APIs but not all APIs are web services.

We have looked at what REST is, and how a client can communicate with a RESTful web service. I have given you just enough details in order to not drown you in lengthy and complicated explanations.

For curious individuals, know that REST came from a doctoral dissertation by Roy Fielding. Formally, the REST architectural style must have 6 constraints — client-server, stateless, cache, uniform interface, layered system and code-on-demand. There’s no better way to learn about REST than reading the dissertation itself.

A RESTful web service is a server that can be accessed by a client through a uniform interface. The client sends requests to agreed-upon URIs, with agreed-upon operations, then the client waits for responses that are in an agreed-upon format.

I learnt a lot from writing this article and I hope you do the same reading it! If you enjoyed reading this, consider checking out other Confusing Web Dev Terminologies Broken Down articles!

The aim of this series is to, well, break down confusing web dev terminologies. If you don’t understand everything in one read-through, then I have failed. Please shout at me in the comments section. If you find any mistakes, please also shout at me in the comments section.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store