Перейти к основному содержимому

13.2 Основные термины API

Термины и определения​

  • REST (Representational State Transfer): Архитектурный стиль, используемый в веб-разработке для построения масштабируемых и удобных взаимодействий между клиентом и сервером.
  • API (Application Programming Interface): Интерфейс, который позволяет программам взаимодействовать друг с другом. В случае REST API, это обычно HTTP-интерфейс, который позволяет клиентам (например, веб-приложениям) общаться с сервером.
  • Endpoint: Конечная точка, URL, по которому можно отправлять запросы к серверу. Например, https://api.example.com/users - это endpoint для получения информации о пользователях.
  • HTTP (Hypertext Transfer Protocol): Протокол передачи данных в сети, используемый для взаимодействия между клиентом и сервером в REST API.
  • GET: HTTP-метод, используемый для получения данных с сервера. Например, когда вы запрашиваете информацию о пользователе, используется GET-запрос.
  • POST: HTTP-метод, используемый для создания новых данных на сервере. Например, добавление нового пользователя.
  • PUT: HTTP-метод, используемый для обновления данных на сервере. Например, изменение информации о пользователе.
  • DELETE: HTTP-метод, используемый для удаления данных на сервере. Например, удаление пользователя.
  • Status Code: Число, возвращаемое сервером в ответ на запрос, чтобы указать его состояние. Например, 200 OK означает успешный запрос, а 404 Not Found - что запрашиваемый ресурс не найден.
  • Request: Запрос, отправляемый от клиента к серверу. Он включает метод (GET, POST, и т. д.), заголовки, параметры и тело запроса (если необходимо).
  • Response: Ответ, получаемый от сервера в ответ на запрос. Он включает статусный код, заголовки и тело ответа (как правило, данные, запрошенные клиентом).
  • JSON (JavaScript Object Notation): Формат данных, широко используемый в REST API для представления информации в виде текста. JSON легко читаем и разбирается как клиентом, так и сервером.
  • Authentication: Процесс аутентификации, который обеспечивает безопасность взаимодействия между клиентом и сервером. Это может включать в себя использование API-ключей, токенов, паролей и других методов.

Запрос (Request) и ответ (Response) в REST API​

Конкретные примеры запроса и ответа в REST API могут варьироваться в зависимости от конкретного API и его конечных точек (endpoints). Ниже приведены простые примеры запросов и ответов для получения информации о пользователе с использованием REST API.

GET запрос​

Запрос на получение информации о пользователе по его ID с использованием HTTP метода GET. URL endpoint для этого запроса может выглядеть следующим образом:

GET /api/users/111

В этом запросе:

  • GET - это HTTP метод, который указывает, что мы хотим получить данные.
  • /api/users/111 - это URL endpoint, который указывает на конкретного пользователя с ID 111.

Пример ответа:

После отправки вышеуказанного запроса, сервер отправляет ответ. Пример ответа может выглядеть следующим образом:

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

{
  "id": 111,
  "username": "Anna",
  "email": "Anna@example.com",
  "age": 25
}

В этом ответе:

  • HTTP/1.1 200 OK - это статусный код, который указывает, что запрос был успешным.
  • Content-Type: application/json - это заголовок, который указывает, что данные в ответе представлены в формате JSON.
  • Тело ответа содержит информацию о пользователе в формате JSON, включая ID, имя пользователя (username), электронную почту (email) и возраст (age).

POST запрос​

Запрос на создание нового пользователя с использованием HTTP метода POST. URL endpoint для этого запроса может выглядеть следующим образом:

POST /api/users

Тело POST-запроса обычно содержит данные нового пользователя в формате JSON. Например:

{
  "username": "new_user",
  "email": "newuser@example.com",
  "age": 25
}

В этом запросе:

  • POST - это HTTP метод, который указывает, что мы хотим создать нового пользователя.
  • /api/users - это URL endpoint, который указывает на конечную точку для создания нового пользователя.
  • Тело запроса содержит данные нового пользователя, включая имя пользователя (username), электронную почту (email) и возраст (age).

Пример ответа:

После отправки вышеуказанного запроса, сервер отправляет ответ. Пример ответа может выглядеть следующим образом:

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

{
  "id": 124,
  "username": "new_user",
  "email": "newuser@example.com",
  "age": 25
}

В этом ответе:

  • HTTP/1.1 201 Created - это статусный код, который указывает, что новый ресурс (пользователь) был успешно создан.
  • Content-Type: application/json - это заголовок, который указывает, что данные в ответе представлены в формате JSON.
  • Тело ответа содержит информацию о новом пользователе, включая присвоенный сервером ID, имя пользователя (username), электронную почту (email) и возраст (age).

PUT запрос​

Запрос на обновление информации о существующем пользователе с использованием HTTP метода PUT. URL endpoint для этого запроса может выглядеть следующим образом:

PUT /api/users/123

Тело PUT-запроса обычно содержит обновленные данные пользователя в формате JSON. Например:

{
  "username": "updated_user",
  "email": "updated@example.com",
  "age": 30
}

В этом запросе:

  • PUT - это HTTP метод, который указывает, что мы хотим обновить данные пользователя.
  • /api/users/123 - это URL endpoint, который указывает на конечную точку для обновления информации о пользователе с ID 123.
  • Тело запроса содержит обновленные данные пользователя, включая новое имя пользователя (username), новую электронную почту (email) и новый возраст (age).

Пример ответа:

После отправки вышеуказанного запроса, сервер отправляет ответ. Пример ответа может выглядеть следующим образом:

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

{
  "id": 123,
  "username": "updated_user",
  "email": "updated@example.com",
  "age": 30
}

В этом ответе:

  • HTTP/1.1 200 OK - это статусный код, который указывает, что обновление данных пользователя было успешным.
  • Content-Type: application/json - это заголовок, который указывает, что данные в ответе представлены в формате JSON.
  • Тело ответа содержит информацию об обновленном пользователе, включая ID, имя пользователя (username), электронную почту (email) и возраст (age).

DELETE запрос​

Запрос на удаление информации о существующем пользователе с использованием HTTP метода DELETE. URL endpoint для этого запроса может выглядеть следующим образом:

DELETE /api/users/123

В этом запросе:

  • DELETE - это HTTP метод, который указывает, что мы хотим удалить данные о пользователе.
  • /api/users/123 - это URL endpoint, который указывает на конечную точку для удаления информации о пользователе с ID 123.

Пример ответа:

После отправки вышеуказанного запроса, сервер отправляет ответ. Пример ответа может выглядеть следующим образом:

HTTP/1.1 204 No Content

В этом ответе:

  • HTTP/1.1 204 No Content - это статусный код, который указывает, что пользователь был успешно удален.

Коды состояния (Status Code)​

REST API использует стандартные коды состояния HTTP (HTTP status codes) для сообщения об результате выполнения HTTP-запросов. Наиболее распространенные коды ответов в REST API:

2xx (Успешные запросы):​

  • 200 OK: Успешный запрос. Сервер возвращает запрошенные данные.
  • 201 Created: Ресурс успешно создан, и его URI указан в заголовке ответа.
  • 204 No Content: Успешный запрос без возврата данных (например, при удалении ресурса).

3xx (Перенаправления):​

  • 301 Moved Permanently: Ресурс перемещен на новый URI, и клиент должен обновить свои закладки.
  • 302 Found или 307 Temporary Redirect: Ресурс временно перемещен на другой URI, и клиент должен использовать новый URI только для данного запроса.

4xx (Ошибки, связанные с запросом клиента):​

  • 400 Bad Request: Запрос клиента некорректен или не может быть обработан сервером.
  • 401 Unauthorized: Необходима аутентификация для доступа к ресурсу.
  • 403 Forbidden: У клиента нет разрешения на доступ к ресурсу.
  • 404 Not Found: Запрошенный ресурс не найден на сервере.
  • 422 Unprocessable Entity: Запрос корректен, но сервер не может обработать его из-за некорректных данных в запросе (например, неверный формат данных).

5xx (Ошибки на стороне сервера):​

  • 500 Internal Server Error: Внутренняя ошибка сервера, которая не позволяет выполнить запрос.
  • 502 Bad Gateway: Прокси-сервер или шлюз получил некорректный ответ от вышестоящего сервера.
  • 503 Service Unavailable: Сервер временно недоступен, часто используется для обслуживания.

Существует множество других кодов, каждый из которых передает определенную информацию о результате выполнения запроса. Разработчики REST API используют эти коды состояния, чтобы клиенты могли адекватно реагировать на различные ситуации и ошибки при взаимодействии с API.

JSON​

JSON (JavaScript Object Notation) - это легковесный формат обмена данными, который удобно использовать для представления структурированных данных. Вот пример синтаксиса JSON:

{
  "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
  }
}

В этом примере:

  • JSON объекты заключены в фигурные скобки {}.
  • Ключи (имена полей) ограничиваются двойными кавычками.
  • Ключи и значения разделяются двоеточием.
  • Пары ключ-значение разделяются запятыми, за исключением последней пары.