Simplifying Rest API

What is REST?

REST is a way of making the internet work. It is based on a set of rules that define how websites should communicate.

REST, which stands for Representational State Transfer, is a very common architectural model for developing web services on the internet. To understand what this means, think about how the web works. When you browse the internet, access different web pages, make online purchases, or interact with applications, all of this involves communication between your device and remote servers. REST is the framework that makes this communication possible and effective.

The main idea behind REST is that everything on the web is considered a “resource.” Resources can be things like user profiles, photos, products in an online store, or any other information you want to share or access online. Each resource is identified by a unique address, called a URI (Uniform Resource Identifier), which is similar to a URL.

To interact with these resources, REST uses HTTP methods such as GET, POST, PUT, and DELETE.

• GET is used to access a copy of a resource.
• POST is used to create a new resource.
• PUT is used to update an existing resource.
• DELETE is used to delete a resource.

REST is a common approach in creating APIs, which are like communication bridges between different websites.

A practical example of a REST API is the Facebook API. This API allows developers to build applications that integrate with Facebook features such as photos, posts, and friends lists. It is like a set of rules that allows applications to connect to Facebook and use its features.

Rest Api Example

I will give a simple example of a REST API that handles “User” resources using the HTTP methods GET, POST, PUT and DELETE. If you want you can practice creating your own API, I describe how in this other article .

1. Get all users (HTTP GET):

To retrieve a list of all users, you send an HTTP GET request to /usersyour API endpoint. The server understands the request and returns a list of all registered users. Each user is like a digital cover letter, with an identification number (ID), name, and email address. It’s like a phone book, but digital.

Request (GET /users):

Response (200 OK):

[
  {
    "id" : 1 ,
     "name" : "John" ,
     "email" : "john@email.com"
  },
  {
    "id" : 2 ,
     "name" : "Maria" ,
     "email" : "maria@email.com"
  }
]    

2. Get a specific user (HTTP GET):

When you want to know details of a particular user, simply make an HTTP GET request to the endpoint /users/{id}, where {id}is the user ID. The server responds with the details of the specific user you requested.

Request (GET /users/1):

Response (200 OK):

{
   "id" : 1 ,
   "name" : "John" ,
   "email" : "john@email.com" 
}

3. Create a new user (HTTP POST):

When a new user registers, you send a POST request to the server with that user’s details to the endpoint /users. You provide the user’s details in the body of the request in JSON format. The server creates the new user and responds with a “business card” for the newly created user, including a new identification number (ID).

Request (POST /users):

{
   "name" : "Carlos" ,
   "email" : "carlos@email.com" 
}

Answer (201 Created):

{
   "id" : 3 ,
   "name" : "Carlos" ,
   "email" : "carlos@email.com" 
}

4. Update a user (HTTP PUT):

When someone wants to change their information, you send an HTTP PUT request with the user ID and updated details to the endpoint /users/{id}. The server makes the updates and returns the new user details.

Request (PUT /users/3):

{
   "name" : "Carlos Silva" ,
   "email" : "carlos.silva@email.com" 
}

Response (200 OK):

{
   "id" : 3 ,
   "name" : "Carlos Silva" ,
   "email" : "carlos.silva@email.com" 
}

5. Delete a user (HTTP DELETE):

If someone decides to leave the club, they make a DELETE request with the ID of the user they want to remove to the endpoint /users/{id}with the ID of the user they want to remove. The server processes the deletion and does not send a response with a body, just the HTTP code 204 No Content, which is like “Done, user deleted!”.

Request (DELETE /users/3):

Response (204 No Content):
(Indicates that the user was successfully removed)

These examples illustrate how basic create, read, update, and delete (CRUD) operations can be performed in a REST API for user resources. Of course, in real applications there is much more to consider, such as security and authentication, but these are the fundamental concepts. It’s like handling a club membership registry, only digital!

What is JSON

As you may have noticed, above we are using a data format called JSON (JavaScript Object Notation). JSON is a way of organizing information that closely resembles the data structures we use in everyday life. It is like a translator that allows computers and applications to understand information in a format that is easy to read and write.

In the Users API example, we use JSON to represent information about users. For example, when we create a new user, we send the user’s details, such as name and email, in a JSON format in the request body. The server understands this JSON, processes the information, and creates the new user.

JSON is made up of key-value pairs, where a “key” is the name of the attribute and the “value” is the content associated with that key. In the example, the “name” key has the value “Carlos Silva” and the “email” key has the value “carlos.silva@email.com”. This structure makes it easy to represent complex data in an organized way.

Additionally, JSON is a widely accepted format on the web and in many APIs, making it a popular choice for transmitting data. It is both human- and machine-readable, making it ideal for communicating data between clients and servers in distributed systems, such as the REST APIs we used as an example.

Conclusion

In short, REST is like the glue that holds the internet together, allowing websites and applications to talk to each other. Think of it as a set of rules that makes communication on the web more efficient.

When you browse the internet, shop online, or use apps, all of this involves your device talking to remote servers. REST is the foundation of this, treating everything on the web as “things” (or resources) with unique addresses, like URLs.

It uses simple methods like GET to get information, POST to create new things, PUT to update, and DELETE to delete. It’s like the pieces of a puzzle that fit together perfectly.

Additionally, using JSON, an organized way of presenting data, makes communication easy for both us and machines. It’s like speaking the same language so that everyone can understand.

In short, REST and JSON are like developers’ best friends when building applications and online services, creating interactive and connected experiences on the internet. By mastering these concepts, developers can build robust and scalable systems in the digital age. It’s like unlocking the secrets of the web!