# JSON API и REST сервисы: Полное руководство

JSON стал стандартом де-факто для RESTful API благодаря своей простоте и универсальности. В этом подробном руководстве мы рассмотрим все аспекты использования JSON в веб-API - от базовых концепций до продвинутых паттернов проектирования.

Что такое REST API?

REST (Representational State Transfer) - это архитектурный стиль для проектирования сетевых приложений. RESTful API использует HTTP методы для выполнения операций над ресурсами.

Основные принципы REST

Stateless (Без состояния) - каждый запрос содержит всю необходимую информацию

Client-Server - разделение клиента и сервера

Cacheable - ответы могут кэшироваться

Uniform Interface - единообразный интерфейс

Layered System - слоистая система

HTTP методы в REST API

GET - Получение данных

GET /api/users/123 Host: api.example.com

Accept: application/json

Ответ:

{ "статус": "успех", "данные": { "id": 123, "имя": "Иван Петров", "email": "ivan@example.com", "роль": "пользователь", "зарегистрирован": "2025-06-15T10:30:00Z" }

}

POST - Создание ресурса

Запрос:

POST /api/users Host: api.example.com Content-Type: application/json { "имя": "Мария Сидорова", "email": "maria@example.com", "пароль": "SecurePass123!"

}

Ответ:

{ "статус": "создано", "данные": { "id": 124, "имя": "Мария Сидорова", "email": "maria@example.com", "создан": "2026-01-26T10:00:00Z" }, "ссылка": "/api/users/124"

}

PUT - Полное обновление ресурса

Запрос:

PUT /api/users/123 Host: api.example.com Content-Type: application/json { "имя": "Иван Иванович Петров", "email": "ivan.petrov@example.com", "роль": "администратор"

}

Ответ:

{ "статус": "обновлено", "данные": { "id": 123, "имя": "Иван Иванович Петров", "email": "ivan.petrov@example.com", "роль": "администратор", "обновлен": "2026-01-26T10:15:00Z" }

}

PATCH - Частичное обновление

Запрос:

PATCH /api/users/123 Host: api.example.com Content-Type: application/json { "email": "new.email@example.com"

}

Ответ:

{ "статус": "обновлено", "данные": { "id": 123, "имя": "Иван Петров", "email": "new.email@example.com", "обновлен": "2026-01-26T10:20:00Z" }

}

DELETE - Удаление ресурса

Запрос:

DELETE /api/users/123

Host: api.example.com

Ответ:

{ "статус": "удалено", "сообщение": "Пользователь успешно удален", "id": 123

}

Структура JSON API ответов

Успешный ответ

{
  "статус": "успех",
  "код": 200,
  "данные": {
    "пользователи": [
      {
        "id": 1,
        "имя": "Иван",
        "email": "ivan@example.com"
      },
      {
        "id": 2,
        "имя": "Мария",
        "email": "maria@example.com"
      }
    ]
  },
  "метаданные": {
    "всего": 50,
    "страница": 1,
    "на_странице": 2,
    "страниц": 25
  }
}

Ответ с ошибкой

{ "статус": "ошибка", "код": 400, "сообщение": "Ошибка валидации", "ошибки": [ { "поле": "email", "сообщение": "Некорректный формат email" }, { "поле": "возраст", "сообщение": "Возраст должен быть больше 0" } ], "timestamp": "2026-01-26T10:00:00Z", "путь": "/api/users"

}

HTTP коды состояния

2xx - Успех

200 OK - Запрос выполнен успешно
201 Created - Ресурс создан
204 No Content - Успех без тела ответа

4xx - Ошибка клиента

400 Bad Request - Некорректный запрос
401 Unauthorized - Требуется аутентификация
403 Forbidden - Доступ запрещен
404 Not Found - Ресурс не найден
422 Unprocessable Entity - Ошибка валидации

5xx - Ошибка сервера

500 Internal Server Error - Внутренняя ошибка
503 Service Unavailable - Сервис недоступен

{ "статус": "ошибка", "код": 404, "сообщение": "Пользователь не найден", "id": 999, "timestamp": "2026-01-26T10:00:00Z"

}

Пагинация

Offset-based пагинация

Запрос:

GET /api/users?страница=2&лимит=10

Ответ:

{
  "данные": [...],
  "пагинация": {
    "текущая_страница": 2,
    "элементов_на_странице": 10,
    "всего_элементов": 125,
    "всего_страниц": 13,
    "следующая": "/api/users?страница=3&лимит=10",
    "предыдущая": "/api/users?страница=1&лимит=10"
  }
}

Cursor-based пагинация

Запрос:

GET /api/users?after=eyJpZCI6MTIzfQ==&лимит=10

Ответ:

{
  "данные": [...],
  "пагинация": {
    "следующий_курсор": "eyJpZCI6MTMzfQ==",
    "есть_следующая": true,
    "лимит": 10
  }
}

Фильтрация и сортировка

Фильтрация

GET /api/users?роль=админ&статус=активен&возраст_от=25&возраст_до=40

Ответ:

{ "данные": [ { "id": 15, "имя": "Алексей", "роль": "админ", "статус": "активен", "возраст": 35 } ], "фильтры": { "роль": "админ", "статус": "активен", "возраст_от": 25, "возраст_до": 40 }, "количество": 1

}

Сортировка

GET /api/users?сортировка=имя:asc,возраст:desc

Ответ:

{
  "данные": [...],
  "сортировка": {
    "поля": ["имя", "возраст"],
    "порядок": ["asc", "desc"]
  }
}

Аутентификация и авторизация

Bearer Token

Запрос:

GET /api/profile Host: api.example.com

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key

Запрос:

GET /api/data Host: api.example.com

X-API-Key: your-api-key-here

Ошибка аутентификации

{ "статус": "ошибка", "код": 401, "сообщение": "Токен истек", "ошибка": "TokenExpiredError", "детали": { "истекает_в": "2026-01-26T09:00:00Z", "сейчас": "2026-01-26T10:00:00Z" }

}

Примеры реализации

Node.js + Express

const express = require('express');
const app = express();

app.use(express.json());

// Middleware для логирования
app.use((req, res, next) => {
  console.log(${req.method} ${req.path});
  next();
});

// GET - Получение списка пользователей
app.get('/api/users', async (req, res) => {
  try {
    const { страница = 1, лимит = 10 } = req.query;

    // Получение данных из БД
    const пользователи = await БД.getPользователи({
      offset: (страница - 1)  лимит,

      limit: parseInt(лимит)
    });

    const всего = await БД.countПользователи();

    res.json({
      статус: 'успех',
      данные: пользователи,
      пагинация: {
        страница: parseInt(страница),
        лимит: parseInt(лимит),
        всего: всего,
        страниц: Math.ceil(всего / лимит)
      }
    });
  } catch (ошибка) {
    res.status(500).json({
      статус: 'ошибка',
      сообщение: 'Внутренняя ошибка сервера',
      ошибка: ошибка.message
    });
  }
});

// POST - Создание пользователя
app.post('/api/users', async (req, res) => {
  try {
    const { имя, email, пароль } = req.body;

    // Валидация
    if (!имя || !email || !пароль) {
      return res.status(400).json({
        статус: 'ошибка',
        код: 400,
        сообщение: 'Обязательные поля: имя, email, пароль'
      });
    }

    // Создание пользователя
    const новыйПользователь = await БД.createПользователь({
      имя,
      email,
      пароль: await хешироватьПароль(пароль)
    });

    res.status(201).json({
      статус: 'создано',
      данные: новыйПользователь
    });
  } catch (ошибка) {
    res.status(500).json({
      статус: 'ошибка',
      сообщение: ошибка.message
    });
  }
});

// PUT - Полное обновление
app.put('/api/users/:id', async (req, res) => {
  try {
    const { id } = req.params;
    const данные = req.body;

    const обновлен = await БД.updateПользователь(id, данные);

    if (!обновлен) {
      return res.status(404).json({
        статус: 'ошибка',
        сообщение: 'Пользователь не найден'
      });
    }

    res.json({
      статус: 'обновлено',
      данные: обновлен
    });
  } catch (ошибка) {
    res.status(500).json({
      статус: 'ошибка',
      сообщение: ошибка.message
    });
  }
});

// DELETE - Удаление
app.delete('/api/users/:id', async (req, res) => {
  try {
    const { id } = req.params;

    const удален = await БД.deleteПользователь(id);

    if (!удален) {
      return res.status(404).json({
        статус: 'ошибка',
        сообщение: 'Пользователь не найден'
      });
    }

    res.status(204).send();
  } catch (ошибка) {
    res.status(500).json({
      статус: 'ошибка',
      сообщение: ошибка.message
    });
  }
});

// Обработка ошибок
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({
    статус: 'ошибка',
    сообщение: 'Что-то пошло не так!',
    timestamp: new Date().toISOString()
  });
});

app.listen(3000, () => {
  console.log('API сервер запущен на порту 3000');
});

Python + Flask

from flask import Flask, request, jsonify
from datetime import datetime
import json

app = Flask(__name__)

# GET - Список пользователей
@app.route('/api/users', methods=['GET'])
def get_users():
    try:
        страница = request.args.get('страница', 1, type=int)
        лимит = request.args.get('лимит', 10, type=int)

        # Получение из БД
        пользователи = БД.get_пользователи(
            offset=(страница - 1)  лимит,
            limit=лимит
        )

        всего = БД.count_пользователи()

        return jsonify({
            'статус': 'успех',
            'данные': пользователи,
            'пагинация': {
                'страница': страница,
                'лимит': лимит,
                'всего': всего,
                'страниц': (всего + лимит - 1) // лимит
            }
        }), 200

    except Exception as e:
        return jsonify({
            'статус': 'ошибка',
            'сообщение': str(e)
        }), 500

# POST - Создание пользователя
@app.route('/api/users', methods=['POST'])
def create_user():
    try:
        данные = request.get_json()

        # Валидация
        обязательные = ['имя', 'email', 'пароль']
        for поле in обязательные:
            if поле not in данные:
                return jsonify({
                    'статус': 'ошибка',
                    'сообщение': f'Отсутствует обязательное поле: {поле}'
                }), 400

        # Создание
        новый = БД.create_пользователь(данные)

        return jsonify({
            'статус': 'создано',
            'данные': новый
        }), 201

    except Exception as e:
        return jsonify({
            'статус': 'ошибка',
            'сообщение': str(e)
        }), 500

# Обработчик ошибок
@app.errorhandler(404)
def not_found(error):
    return jsonify({
        'статус': 'ошибка',
        'код': 404,
        'сообщение': 'Ресурс не найден',
        'путь': request.path
    }), 404

@app.errorhandler(500)
def internal_error(error):
    return jsonify({
        'статус': 'ошибка',
        'код': 500,
        'сообщение': 'Внутренняя ошибка сервера',
        'timestamp': datetime.utcnow().isoformat()
    }), 500

if __name__ == '__main__':
    app.run(debug=True, port=3000)

Версионирование API

В URL

GET /api/v1/users

GET /api/v2/users

В заголовках

GET /api/users

Accept: application/vnd.api.v2+json

В параметрах

GET /api/users?version=2

HATEOAS (Hypermedia)

{ "данные": { "id": 123, "имя": "Иван Петров", "email": "ivan@example.com" }, "ссылки": { "self": "/api/users/123", "заказы": "/api/users/123/orders", "профиль": "/api/users/123/profile", "редактировать": { "href": "/api/users/123", "method": "PUT" }, "удалить": { "href": "/api/users/123", "method": "DELETE" } }

}

Rate Limiting

Ответ при превышении лимита:

{ "статус": "ошибка", "код": 429, "сообщение": "Слишком много запросов", "лимит": { "максимум": 100, "осталось": 0, "сброс": "2026-01-26T11:00:00Z" }

}

Headers:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0

X-RateLimit-Reset: 1706263200

Лучшие практики

1. Используйте существительные, а не глаголы

✅ Правильно:

GET /api/users
POST /api/users
PUT /api/users/123

❌ Неправильно:

GET /api/getUsers
POST /api/createUser
PUT /api/updateUser/123

2. Используйте множественное число

✅ Правильно:

/api/users
/api/products
/api/orders

❌ Неправильно:

/api/user
/api/product
/api/order

3. Вложенные ресурсы

GET /api/users/123/orders GET /api/users/123/orders/456

POST /api/users/123/orders

4. Согласованные коды ответов

Всегда используйте правильные HTTP коды состояния

5. Детальные сообщения об ошибках

Предоставляйте полезную информацию об ошибках

Заключение

JSON API и REST сервисы - это основа современной веб-разработки. Правильное проектирование API с использованием JSON обеспечивает масштабируемость, поддерживаемость и удобство использования.

Ключевые выводы:

Следуйте RESTful принципам
Используйте правильные HTTP методы и коды
Обеспечьте согласованную структуру ответов
Реализуйте пагинацию и фильтрацию
Добавьте версионирование API
Обрабатывайте ошибки правильно
Документируйте ваш API

Следуя этим рекомендациям, вы создадите качественные API, которые будет легко использовать и поддерживать.

Big JSON Team

Что такое REST API?

Основные принципы REST

HTTP методы в REST API

GET - Получение данных

POST - Создание ресурса

PUT - Полное обновление ресурса

PATCH - Частичное обновление

DELETE - Удаление ресурса

Структура JSON API ответов

Успешный ответ

Ответ с ошибкой

HTTP коды состояния

2xx - Успех

4xx - Ошибка клиента

5xx - Ошибка сервера

Пагинация

Offset-based пагинация

Cursor-based пагинация

Фильтрация и сортировка

Фильтрация

Сортировка

Аутентификация и авторизация

Bearer Token

API Key

Ошибка аутентификации

Примеры реализации

Node.js + Express

Python + Flask

Версионирование API

В URL

В заголовках

В параметрах

HATEOAS (Hypermedia)

Rate Limiting

Лучшие практики

1. Используйте существительные, а не глаголы

2. Используйте множественное число

3. Вложенные ресурсы

4. Согласованные коды ответов

5. Детальные сообщения об ошибках

Заключение

Похожие статьи

Python и JSON: Полное руководство по работе с данными

JavaScript и JSON: Полное руководство для разработчиков

JSON Web Tokens (JWT): Полное руководство по аутентификации

Read in English