Everything you need to learn about REST API

APIs make it possible for a frontend developer to request a specific task or resource from the backend. Let’s imagine a restaurant. When you want to order your food, you choose between different endpoints. When you order, you connect the backend of an application which will then send back some data.

I struggled a lot in the beginning when I started working with API and that was mainly because I couldn’t get a clear understanding of what an API is. I always try to explain it with the following example.

Imagine a restaurant where visitors (obviously) sit at a table and eat their food. The food is prepared by chefs in the kitchen. You can see the menu as an API because visitors pick their food, and the kitchen will cook that.

What is REST?

When working with APIs, you’ll be hearing the term REST a lot. REST is an abbreviation for:

• R & E – Representational
• S – State
• T – Transfer

REST is an architectural style that is mainly used for communication between a server and a client.

• REST uses HTTP, so Hypertext Transfer Protocol as a base communication style.
• REST data will be sent in either XML or JSON because they are both “Readable by humans”.

HTTP Methods

When working with APIs, the following HTTP methods are the basic ones for resources.

Verb	Path	Action	Route Name	Description
GET	/movies	index	movies.index	Get all movies
GET	/movies/create	create	movies.create	Get new created movies
POST	/movies	store	movies.store	Create a new movie
GET	/movies/{movie}	show	movies.show	Get data of specific movie
GET	/movies/{movie}/edit	edit	movies.edit	Edit specific movie
PUT/PATCH	/movies/{movie}	update	movies.update	Update a specific movies
DELETE	/movies{delete}	destroy	movies.destroy	Delete a specific movie

Status codes

I won’t mention all the status codes that we’ve got but if you are interested, I recommend you this article from Laravel Daily where they show all available status codes.

JSON Api Specification

Whether you’re making applications in Java, C#, python or you’re making web-based applications in Laravel, there’s a lot you need to think about regarding designing your software. A lot of developers tend to make small mistakes in their JSON file since it’s pretty easy to make small typos. Let’s go over the structure of a JSON file.

{
    "id" : 1,
    "type": "books",
    "attributes": {
        "name": "Deathly Hallows",
        "publication_year": 2007
    },
    "relationships": {
    },
}

Every JSON document starts with an opening curly brace and ends with a closing curly brace. Inside the curly braces, you need to have a comma to show separation.

Members

On the left side of the colon (:), we have something which is called a member name (id, type, name). There are some rules that you need to follow when defining members:

• Needs to have at least one character.
• You can only use characters.
• Member must start and end with global characters.
• Member names need to be lowercase.
• Use your convention for snake cases, kebab case or camel case (But be consistent).

Content

The content of the value of the member. In the example above, it will be 1, books, Deathly Hallows.

{
    "id" : 1,
    "type": "books",
    "attributes": {
        "name": "Deathly Hallows",
        "publication_year": 2007
    },
    "relationships": {
    },
}

Attributes

You have the option to pass in attributes inside a JSON specification. In the example above, you can see attributes as the same attributes you use on your Laravel models:

• Attribute members should be an object.
• Cannot be a relationship.
• Attributes can be empty, or even better removed if you don’t use them.
• In our example, name and publication_year as members inside our attributes.
• There’s no need to add an id in your attribute because they are reserved on the root of the resource object (so outside of our attributes).

Relationships

Sometimes you might need a relationship inside your API because data in an application can be related to one another. Therefore, you could use the optional relationship JSON specification.

{
    "id" : 1,
    "type": "books",
    "attributes": {
        "name": "Deathly Hallows",
        "publication_year": 2007
    },
    "relationships": {
        "author_name": "J. K. Rowling"
    },
}

Conclusion

These are all “basic” topics you need to know before learning APIs. Working with APIs as a beginner might be overwhelming at the beginning. Therefore, I do recommend taking the time to learn all terminology.