Telegram-канал proglibrary - Библиотека программиста | программирование, кодинг, разработка: Технологии

Библиотека программиста | программирование, кодинг, разработка

26 ноября 2023 20:05

🛠 Как проектировать REST API: полезные советы для разработчика

1. Используйте существительные во множественном числе для обозначения коллекций.

# Хорошо
GET /products         
GET /products/{product_id} 

# Плохо
GET /product/{product_id}

2. Не добавляйте ненужные пути в структуру URL-адресов.

# Хорошо
GET /v3/application/listings/{listing_id}

# Плохо
PATCH /v3/application/shops/{shop_id}/listings/{listing_id}

3. Не добавляйте .json или другие расширения к URL-адресу.

4. Не возвращайте массивы в качестве ответов верхнего уровня от эндпоинтов. Верхний уровень ответа должен быть объектом, а не массивом, чтобы обеспечить обратную совместимость и возможность добавления пагинации.

# Хорошо
GET /things returns:
{ "data": [{ ...thing1...}, { ...thing2...}] }

# Плохо
GET /things returns:
[{ ...thing1...}, { ...thing2...}]

5. Не возвращайте структуры map. Вместо этого используйте массивы объектов, чтобы избежать проблем при работе с типизированными языками и не усложнять обработку данных.

# Хорошо
GET /things returns:
{
    "data": [
        { "id": "KEY3", "foo": "bat" }
    ]   
}

# Плохо
GET /things returns:
{
    "KEY3": { "id": "KEY3", "foo": "bat" }
}

6. Используйте строки для всех идентификаторов.

# Хорошо
{ "id": "123" }

# Плохо
{ "id": 123 }

7. Добавляйте префиксы к идентификаторам. Это улучшает читаемость API и помогает различать разные типы идентификаторов.

8. Не используйте 404 для обозначения "not found". Вместо этого рекомендуется использовать другие коды ошибок, чтобы точно указать на отсутствие ресурса.

9. Будьте последовательными. Несоответствие в схемах и структурах может вызвать путаницу и усложнить работу с API.

10. Используйте структурированный формат ошибок. Это облегчает отладку и обработку ошибок на разных уровнях системы.

11. Обеспечьте механизмы идемпотентности. Это важно для предотвращения дублирования операций в условиях нестабильной сети.

12. Используйте строки ISO8601 для временных меток. Строковое представление времени более читаемо и удобно для работы.

👉 Подробнее

#проектирование_систем