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 объекты заключены в фигурные скобки
{}
.
- Ключи (имена полей) ограничиваются двойными кавычками.
- Ключи и значения разделяются двоеточием.
- Пары ключ-значение разделяются запятыми, за исключением последней пары.