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.
Top comments (0)