Методический материал: Что такое API и как с ним работать
(на примерах с JSONPlaceholder)
- Что такое API
API (Application Programming Interface) — это интерфейс взаимодействия между программами.
Простыми словами: API позволяет одной программе запрашивать данные или выполнять действия в другой программе.
Пример:
- приложение погоды получает прогноз через API;
- интернет-магазин получает оплату через API банка;
- мобильное приложение получает список товаров с сервера.
API — это набор правил, по которым программы «разговаривают» друг с другом.
Аналогия
Представьте ресторан:
- Клиент — ваше приложение;
- Официант — API;
- Кухня — сервер с данными.
Клиент не идёт на кухню напрямую. Он передаёт заказ через официанта.
Схема работы:
Клиент → API → Сервер/База данных
Клиент ← API ← Ответ
⸻
- Где используется API
API используется практически везде:
- мобильные приложения;
- сайты;
- интернет-магазины;
- банковские сервисы;
- авторизация через Google;
- Telegram bots;
- карты и геолокация;
- погодные сервисы.
Примеры:
- YouTube API — получение видео;
- Telegram API — отправка сообщений;
- GitHub API — работа с репозиториями;
- Google Maps API — карты.
⸻
- Как работает API
Типичный процесс:
Шаг 1. Клиент отправляет запрос
Например:
GET /posts/1
Запрос означает:
«Дай мне пост с ID = 1»
⸻
Шаг 2. Сервер обрабатывает запрос
Сервер ищет данные.
⸻
Шаг 3. Сервер отправляет ответ
Ответ приходит обычно в формате JSON.
Пример:
{
"userId": 1,
"id": 1,
"title": "sample title",
"body": "sample text"
}
⸻
- Что такое JSON
JSON (JavaScript Object Notation) — формат передачи данных.
Почти все современные API используют JSON.
Пример объекта:
{
"name": "Ivan",
"age": 25,
"city": "Moscow"
}
Основные типы данных JSON
Тип Пример
Строка "hello"
Число 100
Boolean true
Массив [1,2,3]
Объект {}
Null null
Пример массива объектов:
[
{
"id": 1,
"name": "John"
},
{
"id": 2,
"name": "Anna"
}
]
⸻
- HTTP-методы API
API работает через HTTP-запросы.
Основные методы:
Метод Назначение
GET Получить данные
POST Создать
PUT Полностью изменить
PATCH Частично изменить
DELETE Удалить
⸻
GET — получение данных
Пример:
GET /posts
Смысл:
Получить список постов.
⸻
POST — создание данных
Пример:
POST /posts
Смысл:
Создать новый пост.
⸻
PUT — полное изменение
Полностью заменяет объект.
⸻
PATCH — частичное изменение
Меняет только некоторые поля.
⸻
DELETE — удаление
Удаляет объект.
⸻
- Что такое Endpoint
Endpoint — конкретный URL API.
Например, в сервисе JSONPlaceholder:
JSONPlaceholder API
Доступные endpoints:
/posts
/comments
/albums
/photos
/todos
/users
Пример:
https://jsonplaceholder.typicode.com/posts
Этот endpoint возвращает список постов.
⸻
- Знакомство с JSONPlaceholder
JSONPlaceholder Official Website
JSONPlaceholder — бесплатный тестовый REST API.
Используется для:
- обучения;
- тестирования;
- практики работы с API.
Особенность:
Данные фиктивные.
POST/PUT/DELETE работают «понарошку» — сервер делает вид, что изменяет данные.
⸻
- Первый API-запрос
Получим список постов.
Запрос:
https://jsonplaceholder.typicode.com/posts
Ответ:
[
{
"userId": 1,
"id": 1,
"title": "...",
"body": "..."
}
]
Что произошло:
- Клиент отправил GET-запрос.
- Сервер нашёл данные.
- Сервер вернул JSON.
⸻
- Получение одного объекта
Запрос:
https://jsonplaceholder.typicode.com/posts/1
Получаем пост №1.
Ответ:
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat",
"body": "quia et suscipit..."
}
Здесь:
- userId — автор;
- id — идентификатор;
- title — заголовок;
- body — текст.
⸻
- Фильтрация данных
Можно фильтровать через query parameters.
Пример:
https://jsonplaceholder.typicode.com/posts?userId=1
Смысл:
показать посты пользователя 1.
⸻
- POST-запрос (создание)
Отправим новый пост.
Endpoint:
/posts
Тело запроса:
{
"title": "My post",
"body": "Text post",
"userId": 1
}
Пример JavaScript:
fetch('https://jsonplaceholder.typicode.com/posts', {
method: 'POST',
body: JSON.stringify({
title: 'My post',
body: 'Text post',
userId: 1
}),
headers: {
'Content-type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data));
Ответ:
{
"title": "My post",
"body": "Text post",
"userId": 1,
"id": 101
}
⸻
- PUT-запрос (полное изменение)
Изменим пост.
fetch('https://jsonplaceholder.typicode.com/posts/1', {
method: 'PUT',
body: JSON.stringify({
id: 1,
title: 'Updated title',
body: 'Updated text',
userId: 1
}),
headers: {
'Content-type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data));
⸻
- PATCH-запрос (частичное изменение)
Изменим только заголовок.
fetch('https://jsonplaceholder.typicode.com/posts/1', {
method: 'PATCH',
body: JSON.stringify({
title: 'New title'
}),
headers: {
'Content-type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data));
⸻
- DELETE-запрос
Удаление:
fetch('https://jsonplaceholder.typicode.com/posts/1', {
method: 'DELETE'
});
⸻
- Работа с пользователями
Получить пользователей:
https://jsonplaceholder.typicode.com/users
Один пользователь:
https://jsonplaceholder.typicode.com/users/1
Пример ответа:
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "test@test.com"
}
⸻
- Работа с комментариями
Получить комментарии:
https://jsonplaceholder.typicode.com/comments
Комментарии поста:
https://jsonplaceholder.typicode.com/posts/1/comments
⸻
- Работа с TODO
Получить список задач:
https://jsonplaceholder.typicode.com/todos
Пример ответа:
{
"userId": 1,
"id": 1,
"title": "delectus aut autem",
"completed": false
}
⸻
- Коды ответа HTTP
Код Значение
200 Успешно
201 Создано
400 Ошибка запроса
401 Нет авторизации
403 Доступ запрещён
404 Не найдено
500 Ошибка сервера
Пример:
404 Not Found
Значит:
сервер не нашёл ресурс.
⸻
- Тестирование API через браузер
GET-запросы можно открыть прямо в браузере:
https://jsonplaceholder.typicode.com/posts
Но POST/PUT/DELETE так не проверить.
Для этого используют:
- Postman Official Website
- Insomnia
- curl
- код программы
⸻
- Пример на Python
Установка:
pip install requests
Получение данных:
import requests
response = requests.get(
'https://jsonplaceholder.typicode.com/posts/1'
)
data = response.json()
print(data)
POST:
import requests
response = requests.post(
'https://jsonplaceholder.typicode.com/posts',
json={
'title': 'Hello',
'body': 'Test text',
'userId': 1
}
)
print(response.json())
⸻
-
Частые ошибки новичков
-
Неправильный endpoint
Ошибка:
/post
Правильно:
/posts
⸻
- Неверный HTTP метод
Например:
использовать GET вместо POST.
⸻
- Забыли headers
Часто сервер требует:
Content-Type: application/json
⸻
- Неверный JSON
Ошибка:
{
name: Ivan
}
Правильно:
{
"name": "Ivan"
}
⸻
- Практические задания
Задание 1
Получить:
/posts/10
Вывести title.
⸻
Задание 2
Получить все посты пользователя:
?userId=2
⸻
Задание 3
Создать новый TODO.
⸻
Задание 4
Изменить только поле title.
Использовать PATCH.
⸻
- Итоги
API — механизм взаимодействия программ.
Основные элементы:
- endpoint;
- HTTP methods;
- JSON;
- request;
- response;
- status codes.
Минимальный цикл работы с API:
- Отправить запрос
- Получить JSON
- Обработать ответ
- Использовать данные