greatbody
/
freeCodeCamp
mirror of https://github.com/freeCodeCamp/freeCodeCamp.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
freeCodeCamp/guide/russian/rest-api/index.md

8.1 KiB
Raw Blame History

title localeTitle
Rest API Design Дизайн API для отдыха

история

REST обозначает презентационный S татэ протокола Т ransfer Re. Рой Филдинг определил REST в своей докторской диссертации в 2000 году.

Что это?

REST был разработан для обеспечения однородного интерфейса для

  • Определение ресурсов
  • Манипулирование ресурсами
  • Самостоятельные описательные сообщения
  • Использование Hypermedia в качестве механизма состояния приложения (HATEOS)

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

  • #### Основы

| Метод | http://api.co/v2/cars | http://api.co/v2/cars/1234 |
| --- | --- | --- | | GET | Список всех автомобилей | Получить индивидуальный автомобиль | | ПОСТ | Создать новый автомобиль | Ошибка | | PUT | Заменить коллекцию автомобилей новым | Замените автомобиль идентификатором 1234 | | УДАЛИТЬ | Удалить все автомобили | Удалить автомобиль с идентификатором 1234 |

Обратите внимание, что в то время как операции PUT клиент или сервер могут генерировать идентификаторы

  • Существительные хорошие глаголы плохие

  • Используйте существительные для обозначения ресурсов, таких как cars , fruits и т. Д.

  • Использовать глаголы для объявлений действий convertMilesToKms , getNutritionalValues

  • Сингулярное или множественное?

    Используйте правильный грамматик для объявления

    Избегайте /person/145

    Предпочитают /people/154 Предположим вернуть 154-го человека из списка людей

  • Использовать корпус

    Используйте любой из приведенных ниже шаблонов и будьте последовательны!

    | Стили стилей | Пример | | ------------- | ------------- | | UpperCamelCase | http://api.fintech.cp/DailyTransactions/Today | | Нижняя Камелия | http://api.fintech.cp/dailyTransactions/today |
    | snake_case | http://api.fintech.cp/daily_transactions/today |

  • Отношения и ресурсы

  • Ресурсы могут иметь отношения « one-to-many , « many-to-many , « many-to-one и т. Д. Картирование их правильно имеет решающее значение.

  • Сопоставление « один ко многим»

    Например, Tickets/145/messages/4 предлагает отношения «один ко многим» между tickets и messages . Значение 1 билет имеет N сообщений. Сообщение не является автономным ресурсом. У вас не может быть /messages/4 .

  • От многих до многих

    Например, /usergroups/345/users/56 предлагает выбрать 345-ю группу пользователей и получить пользователя с идентификатором 56. Однако один пользователь может быть в нескольких usergroups т.е. /usergroups/209/users/56 также действителен. В таком случае для разделения users ресурсов-депинантов на отдельную конечную точку, например /users/56 и обеспечить привязку ресурсов в /usergroups/209/users/56

  • Параметры API

  • PATH : требуется доступ к ресурсу Eg /cars , /fruits

  • Параметры запроса : опционально фильтровать список Eg /cars?type=SUV&year=2010

  • Тело : специфическая для ресурсов логика. Предварительный запрос. Иногда это может быть как Query, так и body.

  • Заголовок : Должен содержать глобальные или платформенные данные. Например, параметры ключа API, зашифрованные ключи для auth, информация о типе устройства, например, мобильная или настольная или конечная точка, тип данных устройства, например xml или json. Использовать заголовок для передачи данных параметров

  • Коды статуса HTTP

    Использовать правильные коды состояния

    | Коды | Значение | | ------------- |: -------------: | | 1xx | Запрос получен и понят. | | 2xx | Было получено, понято и запрошено действие, запрошенное клиентом. | | 3xx | Клиент должен предпринять дополнительные действия для завершения запроса. Большинство этих кодов состояния используются в перенаправлении URL. | | 4xx | Предназначен для ситуаций, когда, похоже, ошибка была вызвана клиентом. | | 5xx | Сервер не выполнил запрос. |

    Еще немного на 2xx !

  • 201 Создан ресурс. POST /cars должны возвращать HTTP 201, созданный с заголовком location котором указывается, как получить доступ к ресурсу Например, location : api.com/cars/124 в заголовке

  • 202 - Принято

    Используйте это, если задача огромна для запуска. Скажите клиенту, он принял запрос и будет / является процессом / обработкой Не возвращается полезная нагрузка

  • 204 - Нет содержимого

    Используется при удалении DELETE cars/124 Возвращает содержимое. Но также может вернуть 200 OK если API намеревается отправить удаленный ресурс для дальнейшей обработки.

    Опасные ресурсы 5xx !

  • 500 Внутренняя ошибка сервера

  • 504 Тайм-аут шлюза. Сервер не получал своевременного ответа

    Менее известный 4xx предполагает, что вы используете неверный параметр. Может также передавать неверную информацию. Например

    DELETE /cars/MH09234

    возвращает 4xx или сообщение Expecting int car id /car/id got string car/MH09234

дальнейшее чтение

Как разработать отличные API - Parse Developer Day 2013

Бесконечная дискуссия по дизайну REST API от Guillaume Laforge

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