What is API

API (Application Programming Interface),
API is the contract/standard provided by one piece of software (A) to another (B), so that B can create a structured request to A and get a structured response.

What is RESTful API

Representational State Transfer
RESTful APIs refers to web services that conform to the REST architectural style.
REST relies on a stateless, client-server protocol, almost always HTTP.
Treats objects on the server side as resources that can be created or destroyed. We can create server object with a POST request, get it with a GET request, or delete it with a DELETE request etc.

REST style constraints

Stateless

Stateless protocol cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
In computing, a stateless protocol is a communications protocol in which no session information is retained by the receiver, usually a server. A stateless protocol does not require the server to retain session information or status about each communicating partner for the duration of multiple requests. In contrast, a protocol that requires keeping of the internal state on the server is known as a stateful protocol. A TCP connection-oriented session is a stateful connection because both systems maintain information about the session itself during its life.
An example of a stateless protocol is HTTP, meaning that each request message can be understood in isolation.
Contrast this with a traditional FTP server that conducts an interactive session with the user. During the session, a user is provided a means to be authenticated and set various variables (working directory, transfer mode), all stored on the server as part of the user’s state.

Client-server

Separation of concerns is the principle behind the client-server constraints. By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.

Cacheable

In order to improve network efficiency, cache constraints are added to the REST style.
Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
The advantage of adding cache constraints is that they have the potential to partially or completely eliminate some interactions, improving efficiency, scalability, and user-perceived performance by reducing the average latency of a series of interactions.

Uniform Interface

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.

What is an endpoint

An endpoint is a URI/URL where api/service can be accessed by a client application.

HTTP methods

GET POST PUT DELETE
HEAD OPTIONS(returns the allowed HTTP methods) PATCH

Response implements Body

Response implements Body, so it also has the following methods available to it:

  • Body.arrayBuffer()
  • Body.blob()
  • Body.formData()
  • Body.json(): It returns a promise that resolves with the result of parsing the body text as JSON.
  • Body.text(): It returns a promise that resolves with a USVString (text).

    Response.status

    The status read-only property of the Response interface contains the status code of the response (e.g., 200 for a success). It is an unsigned short.
    HTTP response status codes indicate whether a specific HTTP request has been successfully completed. Responses are grouped in five classes:
  • Informational responses (100–199),
  • Successful responses (200–299),
  • Redirects (300–399),
  • Client errors (400–499),
  • Server errors (500–599).
    See this MDN page to learn more about HTTP response status codes.
    Look at these two api handlers:
    1
    2
    3
    4
    5
    6
    7
    export default async function login(req, res) {
      try {
        await auth0.handleLogin(req, res);
      } catch (error) {
        res.status(error.status || 400).end(error.message);
      }
    }
    1
    2
    3
    4
    5
    6
    7
    export default async function me(req, res) {
      try {
        await auth0.handleProfile(req, res, {});
      } catch (error) {
        res.status(error.status || 500).end(error.message);
      }
    }
    If the error contains status information, we set the response status to the error status;
    Otherwise,
    If auth0 did not handleLogin properly, set to 400 Bad Request (The server could not understand the request due to invalid syntax.)
    If auth0 did not get the user profile properly, set to 500 Internal Server Error (The server has encountered a situation it doesn’t know how to handle.)

Next Steps

Re-visit the Promise object, how to make a function return a promise, and how it resolves.

As the Promise.prototype.then() and Promise.prototype.catch() methods return promises, they can be chained.