loading...
Cover image for A simple introduction to REST and how to get started

A simple introduction to REST and how to get started

thabisegoe profile image Thabi Updated on ・5 min read

My goal is to share what I have learned about REST. I often apply methods in web development without understanding the history behind them. So, what is REST? What does web development have to do with resting?

When I started coding, I often ran into tutorials that use data from external resources. Projects such as building a weather app, an online book shop, and a netflix replica. These tutorials often use data from places like Github, Youtube, Twitter or various other APIS.

What is an API?

API stands for Application Programming Interface, it is a way for two different applications to communicate. Most large companies have built their own APIs. APIs in simple terms give you data, and this data is used in various ways.
Let's say you want to create an appointment booking app. You can choose to use one of Google's many APIs like Google Maps and calendar to make things easier for you.

What is REST?

REST stands for Representational State Transfer, it was introduced by Roy Fielding in 2000. It is a software architectural style that created a standard that allowed two servers to communicate and exchange data anywhere in the world. REST is standardized this way, to make it easier to work with other RESTful APIs.

What does RESTful API mean?

RESTful simply means a service provides a REST interface that you can communicate with.

A RESTful API is an application programming interface (API) that uses HTTP requests to interact with data. A RESTful API basically is a service that (hopefully) follows the rules.

There are 6 key constraints which define a "true" RESTful API.

Some of the criteria of REST, simplified:

  • Be consistent, you ask for data in the same way and get back the same data back. You should follow specific guidelines like naming conventions, link or data formats. You should be able to access the resources using a common approach like HTTP methods.
  • You should compose your API into a clear set of entities, and give them unique url identifiers like www.example.com/albums/song/1
  • API should be idempotent (which means you can keep repeating the same operation, and should still expect the same value back). Example if you choose to delete an album with an ID of 52, it should not impact other data. It may give you an error letting you know that the album has already been deleted, but it should not delete random albums.
  • It should be stateless which means the server should not remember anything about the user who uses the API.

Have you ever received a link from a friend only for it to say, access denied? The developer might have chosen that option, but it goes against the principles of RESTful. Many websites aim to be RESTful which is not always achievable. For example, many websites are stateful, they change the information you see based on cookie sessions.

Back in the day (even now, who am I kidding?), it was common to see a URL that looked like this,

www.example.com/sessionid=AIsdlasdklMVgyfrfksoskeikskZPF63erfswwqwewq

this does not tell us anything right? I would not know what to expect from this url.

If you compare it to a url like

www.example.com/albums/1

or

www.example.com/rihanna/albums/1

you would have clearer expectations.

How does everything interact?

I will be focusing on a small aspect of REST when it is applied to Web services.

HTTP-based RESTful APIS are defined with the following aspects:

  • a base URI such as https://dev.to/
  • a media type that defines the data elements (e.g. JSON)
  • standard HTTP methods (this is a basic explanation, there is a lot more that goes into HTTP methods):
Method Description Example
GET Used to "read" or fetch data Get's a list of existing customers
POST Used to create new resources Submitting a new customers details on a form
PUT Used to update resources Updating a customers first name, you will need to send the full parameters to update it : ({"first":"Maddy", "last":"Stone"})
DELETE Used to delete resources Deleting a customer from your database
PATCH Used to making partial updates to resources Used if you want to change a specific value ({"first":"Jamie"})

It is conventional to create a unique address for resources. For example, if you had a database of your music collection, the root URL would be something like:

www.example.com/api

Your albums would be considered as a resource, and usually have an ID that identifies each one.

www.example.com/api/albums

Let's say you stored your favourite Rihanna album with an ID of 15. You would locate it here:

www.example.com/api/albums/15

You would be able to interact with your database:

URL Method Action
/api/albums GET Get a list of all the albums you have in your database
/api/albums/1 GET Get this specific album with the id of 1
/api/albums POST Post a new album, you can use a generateID function to automatically create an ID everytime you add a new album
/api/albums/:id DELETE Delete a specific album with the id you choose. :id is replaced with an id

The above approach follows a model created by Leonard Richardson. It does not fully meet the original "REST API" criteria.

A good path to follow is looking at how major companies define their approach to RESTful APIs. Reading documentation is a great way to learn about best practices, and many offer walkthroughs on interacting with their API.

I recommend looking at:

  • Twilio : one of the coolest APIs available, they give you various examples of things you can build using their services and even have tutorials
  • Stripe : simple, straightforward guide
  • Dropbox: I really like that Dropbox gives you an option of choosing the language you prefer working in
  • Microsoft REST API guidelines
  • Github
  • Plaid

To summarize, REST is usually mentioned in reference to RESTful APIs which developers use to interact with APIs. It is a set of guidelines to create web applications.

Posted on by:

thabisegoe profile

Thabi

@thabisegoe

visual communications design graduate from South Africa. I like to tell a story with beautiful, expressive, well-communicated web design. always learning. connect with me on twitter!

Discussion

markdown guide