Skip to main content

13.2 Basic API terms

Terms and Definitions​

  • REST (Representational State Transfer): An architectural style used in web development to build scalable and user-friendly interactions between the client and server.
  • API (Application Programming Interface): An interface that allows programs to interact with each other. In the case of a REST API, this is typically an HTTP interface that enables clients (e.g., web applications) to communicate with the server.
  • Endpoint: A specific URL to which requests can be sent to the server. For example, https://api.example.com/users is an endpoint for retrieving information about users.
  • HTTP (Hypertext Transfer Protocol): A data transfer protocol on the network, used for interaction between the client and server in a REST API.
  • GET: HTTP method used to retrieve data from the server. For instance, when you request information about a user, a GET request is used.
  • POST: HTTP method used for creating new data on the server. For example, adding a new user.
  • PUT: HTTP method used for updating data on the server. For example, changing user information.
  • DELETE: HTTP method used for deleting data on the server. For example, deleting a user.
  • Status Code: A number returned by the server in response to a request to indicate its state. For example, 200 OK means a successful request, and 404 Not Found means the requested resource was not found.
  • Request: A request sent from the client to the server. It includes the method (GET, POST, etc.), headers, parameters, and request body (if necessary).
  • Response: A response received from the server in reply to a request. It includes the status code, headers, and response body (typically, data requested by the client).
  • JSON (JavaScript Object Notation): A data format widely used in REST APIs to represent information as text. JSON is easily readable and parseable by both the client and the server.
  • Authentication: The authentication process that ensures security in the interaction between the client and the server. This may involve the use of API keys, tokens, passwords, and other methods.

Request and Response in REST API​

Specific examples of a request and response in a REST API can vary depending on the specific API and its endpoints. Below are simple examples of requests and responses for obtaining user information using a REST API.

GET​

Request to Retrieve User Information by ID Using the HTTP GET Method. The URL endpoint for this request can look as follows:

GET /api/users/111

In this request:

  • GET this is the HTTP method indicating that we want to retrieve data.
  • /api/users/111 this is the URL endpoint pointing to a specific user with ID 111.

Example Response:

After sending the above request, the server sends a response. An example response might look like this:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 111,
  "username": "Anna",
  "email": "[email protected]",
  "age": 25
}

In this response:

  • HTTP/1.1 200 OK - this is the status code indicating that the request was successful.
  • Content-Type: application/json - this is the header indicating that the data in the response is in JSON format.
  • The response body contains user information in JSON format, including ID, username, email, and age.

POST​

Request to Create a New User Using the HTTP POST Method. The URL endpoint for this request can look as follows:

POST /api/users

The request body contains data for the new user in JSON format. For example:

{
  "username": "new_user",
  "email": "[email protected]",
  "age": 25
}

In this request:

  • POST - this is the HTTP method indicating that we want to create a new user.
  • /api/users - this is the URL endpoint pointing to the endpoint for creating a new user.
  • The request body contains data for the new user, including username, email, and age.
Example Response:

After sending the above request, the server sends a response. An example response might look like this:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 124,
  "username": "new_user",
  "email": "[email protected]",
  "age": 25
}

In this response:

  • HTTP/1.1 201 Created - this is the status code indicating that a new resource (user) has been successfully created.
  • Content-Type: application/json - this is the header indicating that the data in the response is in JSON format.
  • The response body contains information about the new user, including the ID assigned by the server, username, email, and age.

PUT​

Request to Update Existing User Information Using the HTTP PUT Method. The URL endpoint for this request can look as follows:

PUT /api/users/123

The request body contains the updated user data typically in JSON format. For example:

{
  "username": "updated_user",
  "email": "[email protected]",
  "age": 30
}

In this request:

  • PUT - this is the HTTP method indicating that we want to update user data.
  • /api/users/123 - this is the URL endpoint pointing to the endpoint for updating information about the user with ID 123.
  • The request body contains the updated user data, including the new username, email, and age.

Example Response:

After sending the above request, the server sends a response. An example response might look like this:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "username": "updated_user",
  "email": "[email protected]",
  "age": 30
}

In this response:

  • HTTP/1.1 200 OK - this is the status code indicating that the update of user data was successful.
  • Content-Type: application/json - this is the header indicating that the data in the response is in JSON format.
  • The response body contains information about the updated user, including the ID, username, email, and age.

DELETE​

Request to Delete Existing User Information Using the HTTP DELETE Method. The URL endpoint for this request can look as follows:

DELETE /api/users/123

In this request:

  • DELETE - this is the HTTP method indicating that we want to delete user data.
  • /api/users/123 - this is the URL endpoint pointing to the endpoint for deleting information about the user with ID 123.

Example Response:

After sending the above request, the server sends a response. An example response might look like this:

HTTP/1.1 204 No Content

In this response:

  • HTTP/1.1 204 No Content - this is the status code indicating that the user has been successfully deleted.

Status Codes​

REST API utilizes standard HTTP status codes to communicate the outcome of HTTP requests. The most common response codes in REST API include:

2xx (Successful Requests):​

  • 200 OK: Successful request. The server returns the requested data.
  • 201 Created: Resource successfully created, and its URI is provided in the response header.
  • 204 No Content: Successful request with no data returned (e.g., when deleting a resource).

3xx (Redirections):​

  • 301 Moved Permanently: Resource has been moved to a new URI, and the client should update its bookmarks.
  • 302 Found or 307 Temporary Redirect: Resource is temporarily moved to another URI, and the client should use the new URI only for the current request.

4xx (Client-Side Request Errors):​

  • 400 Bad Request: Client's request is incorrect or cannot be processed by the server.
  • 401 Unauthorized: Authentication is required to access the resource.
  • 403 Forbidden: The client does not have permission to access the resource.
  • 404 Not Found: The requested resource is not found on the server.
  • 422 Unprocessable Entity: The request is correct, but the server cannot process it due to incorrect data in the request (e.g., invalid data format).

5xx (Server-Side Errors):​

  • 500 Internal Server Error: Internal server error preventing the request from being fulfilled.
  • 502 Bad Gateway: Proxy server or gateway received an invalid response from an upstream server.
  • 503 Service Unavailable: The server is temporarily unavailable, often used for maintenance.

There are many other status codes, each conveying specific information about the outcome of the request. REST API developers use these status codes to allow clients to appropriately respond to various situations and errors when interacting with the API.

JSON​

JSON (JavaScript Object Notation) is a lightweight data interchange format that is convenient for representing structured data. Here is an example of JSON syntax:

{
  "name": "John Doe",
  "age": 30,
  "isStudent": false,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "zipCode": "12345"
  },
  "hobbies": ["reading", "hiking", "painting"],
  "scores": {
    "math": 95,
    "science": 88,
    "history": 75
  }
}

In this example:

  • JSON objects are enclosed in curly braces {}.
  • Keys (field names) are enclosed in double quotes.
  • Keys and values are separated by a colon.
  • Key-value pairs are separated by commas, except for the last pair.