Understanding Rest API's - part 1
Tags: javascript, programming, tutorial, api
Published: 2023-11-02 01:45:53

### Table of content

1. [Introduction](#introduction)
- [What is REST?](#what-is-rest)
-  [Key Concepts in REST](#key-concepts-in-rest)
- [Best Practices for Frontend Development with RESTful APIs](#best-practices-for-frontend-development-with-restful-apis)
- [Demo](#demo)
-  [Conclusion](#conclusion)


##Introduction
In this series, you will walk through REST API in software development. 
As a frontend developer, the core of your existence revolve around interacting with data. This exists either by way of sending, modifying, or just viewing data from the backend. The link and path to fulfilling these destiny lies with the infamous term, API. 

Application Programming Interfaces (APIs) are the backbone of modern web and mobile applications. 

There are different patters or architecture of API's, of these types, we'd be dwelling on REST API.

Representational State Transfer (REST) is one of the most popular architectural pattern for designing API's. In this  article, we'll dive into the world of RESTful APIs. We'd start by introducing the basics, principles, and key concepts of REST.

## **What is REST?**
REST stands for Representational State Transfer. It is an architectural style, not a strict set of rules or standards.
The basic concept of RESTful API is to provide a standardized way for different software applications to communicate with each other over the internet. RESTful APIs are designed around a set of principles that help you create scalable, efficient, and stateless web services. These principles include:

### **Statelessness**: 
Each request from a client to the server must contain all the information needed to understand and process the request. The server should not store any client context between requests. This makes REST APIs highly scalable and allows them to handle a large number of clients.

### **Client-Server Architecture**: 
The client and server are separate entities, each responsible for a specific concern. The client is responsible for the user interface and user experience, while the server is responsible for processing requests and managing resources.

## **Uniform Interface**: 
REST APIs have a uniform and consistent interface. This simplifies both the client and server, as they know what to expect. The uniform interface is typically composed of the following constraints:

##**Resource**: 
Resources are the key abstractions in REST. A resource can be any entity or object, such as a user, product, or blog post. Resources are identified by URLs.

## **HTTP Methods**: 
REST APIs use HTTP methods (`GET`, `POST`, `PUT`, `DELETE`, etc.) to perform actions on resources. For example, `GET` retrieves a resource, while `POST` creates a new resource.

## **Stateless Communication**: 
Every request from the client to the server must contain all the information needed to understand and process the request. No session state is stored on the server.

## **Representation**: 
Resources can have multiple representations, such as JSON, XML, or HTML. Clients interact with these representations to access or modify resources.

## **Self-descriptive Messages**: 
Each message should include enough information for the receiver to understand how to process the message. This can include the media type (e.g., JSON) and link relations (e.g., hyperlinks).

##**Hypermedia as the Engine of Application State (HATEOAS)**:
 Resources should include links to related resources, allowing clients to navigate the API dynamically. This reduces the need for clients to have prior knowledge of the API's structure.

## **Layered System**: 
REST APIs can be layered, allowing intermediaries like load balancers, caching servers, and firewalls to be placed between clients and servers. This simplifies scalability and security.

##Key Concepts in REST
To better understand REST, let's explore some key concepts:

## **Resources and URIs**
Resources are central in REST. They represent entities in the system. Each resource is identified by a Uniform Resource Identifier (URI), which is typically a URL. For example, a blog application might have resources like /posts and /users, each accessible via a unique URI.

## **HTTP Methods**
RESTful APIs use HTTP methods to perform actions on resources. Common HTTP methods include:

* **`GET`**: Retrieve a representation of the resource.
* **`POST`**: Create a new resource.
* **`PUT`**: Update an existing resource or create one if it doesn't exist.
* **`DELETE`**: Remove a resource.
* **`PATCH`**: Partially update a resource.
* **`HEAD`**: Retrieve headers for a resource without the body.
* **`OPTIONS`**: Retrieve information about communication options.
*The use of these HTTP methods corresponds to CRUD (Create, Read, Update, Delete) operations in REST.*

## **Representations**
Resources can have multiple representations, typically in formats like JSON, XML, or HTML. These representations provide different views of the same resource, and clients can choose the format that best suits their needs.

## **Status Codes**
HTTP status codes shows the result summary of an operation. Some common status codes in REST include:

* **200 OK**: The request was successful.
* **201 Created**: The request resulted in the creation of a new resource.
* **204 No Content**: The request was successful, but there is no response body.
* **400 Bad Request**: The client sent an invalid request.
* **404 Not Found**: The requested resource does not exist.
* **500 Internal Server Error**: The server encountered an error.
Understanding these status codes is crucial for debugging and handling errors in RESTful APIs.


##How Frontend Developers Interact with RESTful APIs

Frontend developers typically work with RESTful APIs in web applications to retrieve and display data, submit forms, and perform various operations. Here's how you can interact with RESTful APIs from the frontend:

* **HTTP Requests**: Use JavaScript or a frontend framework/library to send HTTP requests (e.g., using the Fetch API, Axios, or jQuery) to the API endpoints. These requests typically use HTTP methods such as `GET`, `POST`, `PUT`, and `DELETE`.

* **JSON Parsing**: Most RESTful APIs return data in JSON format. Frontend developers need to parse this JSON data to extract and display the relevant information on the web page.

* **Authentication**: Some APIs require authentication (e.g., API keys, tokens) to access protected resources. You'll need to include authentication headers or credentials in your requests.

* **Error Handling**: Handle errors gracefully. This includes checking for HTTP status codes (e.g., 404 for "Not Found," 401 for "Unauthorized") and displaying appropriate error messages to users.

* **Asynchronous Operations**: REST API calls are typically asynchronous. Ensure that your frontend code handles asynchronous operations and callbacks, or use modern techniques like Promises or async/await.

* **Form Handling**: For operations that require sending data to the server (e.g., creating or updating resources), you'll need to handle form submissions and send POST or PUT requests.

* **Pagination**: If your application displays a large amount of data, you may need to implement pagination to request and display data in smaller chunks.

* **Cross-Origin Requests**: If your frontend and backend run on different domains, you may need to address cross-origin issues. Consider enabling CORS (Cross-Origin Resource Sharing) on the server or use JSONP.

* **Testing and Debugging**: Use developer tools, browser extensions, or dedicated API testing tools (e.g., Postman) to test and debug your API requests.

* **Documentation**: Consult the API documentation provided by the backend team or service provider to understand the available endpoints, data formats, and authentication requirements.


##Best Practices for Frontend Development with RESTful APIs



Here are some best practices for frontend developers working with RESTful APIs:


* **Modular Code**: Organize your code by separating API-related logic into separate modules or services to keep it clean and maintainable.

* **Error Handling**: Implement robust error handling to provide meaningful feedback to users and capture errors for debugging.

* **API Abstraction**: Consider creating an abstraction layer for your API interactions to encapsulate API-specific details and improve code reusability.

* **Loading Indicators**: Use loading indicators or spinners to give users feedback when making API requests.

* **Caching**: Implement caching mechanisms to reduce the number of unnecessary API requests and improve performance.

* **Security**: Be cautious with sensitive data and authentication tokens. Avoid exposing them in client-side code.

* **Rate Limiting**: Respect any rate limiting or throttling imposed by the API provider to prevent overuse.

* **Testing**: Thoroughly test your API interactions and

##Demo
A demonstration of interacting with a REST API in js
```
// Base URL of the API
const baseUrl = 'https://api.example.com/books';

// Function to handle errors
const handleErrors = (response) => {
  if (!response.ok) {
    throw new Error(`Request failed with status: ${response.status}`);
  }
  return response;
};

// GET Method - Retrieve a list of books
fetch(baseUrl)
  .then(handleErrors)
  .then((response) => response.json())
  .then((data) => {
    console.log('GET Request - List of Books:', data);
  })
  .catch((error) => {
    console.error('GET Request Error:', error);
  });

// POST Method - Create a new book
const newBook = {
  title: 'New Book',
  author: 'John Doe',
};

fetch(baseUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(newBook),
})
  .then(handleErrors)
  .then((response) => response.json())
  .then((data) => {
    console.log('POST Request - Created Book:', data);
  })
  .catch((error) => {
    console.error('POST Request Error:', error);
  });

// PATCH Method - Partially update an existing book
const bookToUpdate = {
  title: 'Updated Book Title',
};

fetch(`${baseUrl}/1`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(bookToUpdate),
})
  .then(handleErrors)
  .then((response) => response.json())
  .then((data) => {
    console.log('PATCH Request - Updated Book:', data);
  })
  .catch((error) => {
    console.error('PATCH Request Error:', error);
  });

// PUT Method - Update an existing book
const updatedBook = {
  title: 'Revised Book Title',
  author: 'Jane Smith',
};

fetch(`${baseUrl}/1`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(updatedBook),
})
  .then(handleErrors)
  .then((response) => response.json())
  .then((data) => {
    console.log('PUT Request - Updated Book:', data);
  })
  .catch((error) => {
    console.error('PUT Request Error:', error);
  });

// OPTIONS Method - Retrieve options for the resource
fetch(baseUrl, {
  method: 'OPTIONS',
})
  .then(handleErrors)
  .then((response) => response.json())
  .then((data) => {
    console.log('OPTIONS Request - Resource Options:', data);
  })
  .catch((error) => {
    console.error('OPTIONS Request Error:', error);
  });

// HEAD Method - Retrieve headers for a resource without the body
fetch(`${baseUrl}/1`, {
  method: 'HEAD',
})
  .then(handleErrors)
  .then((response) => {
    console.log('HEAD Request - Resource Headers:', response.headers);
  })
  .catch((error) => {
    console.error('HEAD Request Error:', error);
  });


```

In this Demo, we demonstrate how to use the Fetch API to perform the various HTTP methods:

* `GET`: Retrieve a list of books.
* `POST`: Create a new book.
* `PATCH`: Partially update an existing book.
* `PUT`: Update an existing book.
* `OPTIONS`: Retrieve options for the resource.
* `HEAD`: Retrieve headers for a resource without the body.

For your use case, this will be the baseURL to which all your calls and interactions will be made 'https://api.example.com/books'  

Also, this is a very basic method of handling response data, you will need to go as wild as your case requires.


##Conclusion
In this first part of your journey into RESTful APIs, you have seen and followed through an detailed introduction to the principles and key concepts of REST. You have explored the principles of statelessness, the client-server architecture, and the uniform interface, which are the foundation of RESTful design.

In the next part, you will go deeper, discussing resource design, authentication, best practices, and more. By the end of this series, you'll be well-equipped to design and consume RESTful APIs effectively. Stay tuned for the next part!