9 советов, которые нужно знать перед созданием вашей следующей успокаивающей системы
Архитектура REST - это наиболее распространенная архитектура для создания интерактивного API для веб-служб. REST был впервые представлен Роем Филдингом в 2000 году. Спустя 20 лет REST API используется почти на всех предприятиях.
Архитектура REST не предоставляет никаких рекомендаций или стандартов для разработки API. Все API Restful должны соответствовать 6 ограничениям, которые были созданы Роем Филдингом. Большинство из вас знает об этих 6 ограничениях: архитектура клиент-сервер, кэшируемость, отсутствие состояния, многоуровневая система, унифицированный интерфейс и код по запросу.
Поскольку нет конкретных рекомендаций по разработке Rest API, мы должны разработать Rest API очень тщательно, чтобы в будущем у нас не было никаких проблем, связанных с безопасностью, производительностью или простотой использования.
Поскольку REST существует уже 20 лет, многие люди писали о лучших практиках разработки REST API. В этой статье будут рассмотрены 9 наиболее важных приемов создания API отдыха.
1) Всегда используйте существительные вместо глаголов в конечной точке Rest
В REST глагол уже присутствует в URI. Всегда следует избегать использования глагола в URI REST API. Когда вы вызываете конечную точку отдыха, всегда обязательно определять метод HTTP с запросом. Ниже приведены распространенные методы HTTP:
POST: Create a new data in server GET: Retrieve data from server PUT: Update resource data in server PATCH:Update partial resource data in server DELETE: Delete data from server
По сути, эти HTTP-методы уже вводят глаголы в URI, поэтому нет смысла вводить другой глагол. Возьмем пример для конечной точки, чтобы создать сообщение в службе блога. Мы можем создать POST URI, как две конечные точки ниже.
http://localhost:8081/v1/createnewblog http://localhost:8081/v1/blogs
Теперь мы вызываем этот метод POST, так что уже известно, что мы создаем блог, добавление createnewblog в URL не помогает. Кроме того, добавление глагола в URL-адрес просто сбивает пользователя с толку. Предположим, что если мы решим добавить createnewblog в конечную точку, то какая конечная точка будет извлекать блог, будет ли это http: // localhost: 8081 / v1 / getblog »? Если мы не используем глагол, это будет очень просто. Если нам нужно получить продукт, мы можем использовать метод GET по URL-адресу http: // localhost: 8081 / v1 / blogs / {blog Id}
2) Логическое вложение на конечных точках предпочтительно, но не обязательно.
Я читал во многих местах, что при проектировании конечных точек для отдыха всегда рекомендуется группировать ресурсы, содержащие связанную информацию. Это в основном означает, что если какой-то объект содержит другой объект, он должен быть отражен в URL-адресе.
Например, в каждом блоге могут быть комментарии. Таким образом, получить комментарии конкретной конечной точки блога будет похоже.
http://localhost:8081/v1/blogs/1/comments/
Вам также может потребоваться получить комментарии, сделанные пользователями, поэтому для этого вам нужно создать другой URI. Это одна из проблем с логическим вложением в URI, вам нужно создать избыточный URI, чтобы получить список комментариев. Вложенный URI также может стать очень длинным, скажем, вы хотите, чтобы все сотрудники работали в компании XYZ и в отделе ABC. URI для запроса будет примерно таким:
http://localhost:8081/v1/companies/XYZ/departments/ABC/employees
Как правило, когда ваши данные строго иерархичны, не слишком глубоко вложены и отношения не меняются слишком часто, в таких случаях предпочтительным является вложенный URI. В других случаях использование вложенности в URI не является обязательным. Вы можете проверить плюсы и минусы использования вложенных ресурсов в URI здесь и выбрать соответствующий вариант.
3) Изящно обрабатывать ошибки и возвращать стандартные коды ошибок
Очень важно правильно обрабатывать ошибки. На самом деле не имеет смысла, что если вы получите неправильный запрос, вся служба выйдет из строя. Сервер всегда должен выдавать правильные ошибки, чтобы пользователь мог знать, в чем проблема. Все API-интерфейсы Rest должны возвращать правильный код ответа HTTP, например, коды состояния 4 ** зарезервированы для ошибок клиента, а 5 ** зарезервированы для ошибок сервера. Ниже приведены некоторые общие коды отдыха:
400(Bad Request): It indicates something is wrong with request. 401(Unauthorized): It indicates user is not able to authenticate. 403(Forbidden): It indicates user don't have permission to access resource. 404(Not Found): It indicates unable to found resource. 500(Internal Server Error): 502(Bad Gateway): 503(Service Unavailable):
Обработка ошибок не должна ограничиваться только правильными кодами HTTP. В ответе об ошибке должно быть также дано правильное описание ошибки вместе с кодом состояния. Например, в ответе ниже, просто посмотрев на ответ об ошибке, мы можем определить, что мы не передали идентификатор клиента в запросе.
{
"error": {
"timeStamp": "18-07-2017 06:49:25"
"message": "Mandatory Parameter Customer Id is missing from Request.",
"status": "400",
"code": 0001
}
}
Вы также можете добавить некоторую другую информацию в свой ответ об ошибке, например, Facebook в своем ответе об ошибке также отправляет идентификатор трассировки. Все должны позаботиться о том, чтобы все ответы об ошибках были идентичны для всех REST API в организации.
4) Разрешить фильтрацию, сортировку и разбиение на страницы
Бывают случаи, когда ваш REST API будет иметь много данных для отправки в ответ. Например, пользователь может захотеть получить все блоги по определенной теме. Таких блогов могут быть миллионы. Если вы вернете весь список в одном ответе, это может создать множество проблем - например, вы можете столкнуться с исключениями нехватки памяти. Всегда необходимо поддерживать разбиение на страницы. Пользователям также может потребоваться доступ только к некоторой части всех блогов. Как пользователь хочет получить доступ только к сообщениям, созданным в течение месяца. В таких случаях поможет фильтрация.
И фильтрация, и разбивка на страницы помогают нам повысить производительность API. Пользователям также может потребоваться отсортировать ответы на основе определенного поля, поэтому сортировка также должна поддерживаться.
5) Никогда не отвечайте простым текстом
Хотя это не навязано Rest, в большинстве случаев JSON идет рука об руку с REST. Всегда рекомендуется отвечать на запросы в формате JSON, а не на обычный текст. Однако просто отправить ответ в формате JSON - это не единственное, что вам нужно сделать. Вам также необходимо предоставить заголовок Content-Type в ответ со значением application / JSON. При желании вы также можете использовать другие форматы в ответах, например XML, но XML в ответах широко не используется, поскольку требует дополнительной обработки.
6) Никогда не идите на компромисс в отношении безопасности конечной точки
Все коммуникации между клиентом и сервером должны быть защищены. Всегда старайтесь включить TLS для вашего сервера, так как это защитит ваши данные при передаче. В современных библиотеках включить SSL очень просто.
Нам также необходимо включить надлежащий контроль доступа на основе ролей. В конце концов, никому не понравится, что его информация будет доступна другим пользователям. Вы всегда должны давать пользователю минимальное разрешение на выполнение необходимого действия. Например, если какой-либо тип пользователя может только искать ресурсы, тогда следует предоставить только разрешение, необходимое для вызова API поиска. Также следует всегда помнить, что отправка любых конфиденциальных данных в URL - это большой недостаток. Поэтому вам никогда не следует разрабатывать REST API, который принимает пароли в URI.
7) Попытайтесь принять спецификацию OpenAPI
Согласно официальной документации определения спецификации OpenAPI:
Спецификация OpenAPI (OAS) определяет стандартный, не зависящий от языка интерфейс для RESTful API, который позволяет людям и компьютерам обнаруживать и понимать возможности службы без доступа к исходному коду, документации или через проверку сетевого трафика. При правильном определении потребитель может понимать удаленную службу и взаимодействовать с ней с минимальным объемом логики реализации.
В OpenAPI вместо того, чтобы реализовывать API, прежде всего, документ контракта разрабатывается и согласовывается еще до того, как разработка может даже начаться. Этот контракт в основном написан в файлах YAML, и у нас есть различные инструменты, такие как редактор swagger, которые позволяют легко редактировать и читать содержимое YAML. Даже все потребители вашего API могут сгенерировать клиентский комплект только с этим контрактом, не требуя дополнительной информации.
OpenAPI поставляется с множеством инструментов, которые помогут вам не только спроектировать API, но и на протяжении всего жизненного цикла вашего API. Вы можете узнать больше о спецификации OpenAPI здесь.
8) HATEOAS - ваш друг
HATEOAS расшифровывается как гипертекст как двигатель состояния приложения. Здесь гипертекст относится к любому контенту, который содержит ссылки на другие носители, такие как видео, аудио, изображения и текст. В контексте REST HATEOAS означает, что в ответ у нас будут ссылки на другие ресурсы. Просто возьмите пример Github API, ниже приведен 1 образец ответа. В ответ вы можете увидеть, что существует множество URI для разных ресурсов.
{
"pull_request": {
"patch_url": null,
"html_url": null,
"diff_url": null
},
"created_at": "2012-11-14T15:25:33Z",
"comments": 0,
"milestone": null,
"title": "New logo",
"body": "We should have one",
"user": {
"login": "pengwynn",
"gravatar_id": "7e19cd5486b5d6dc1ef90e671ba52ae0",
"avatar_url": "https://secure.gravatar.com/avatar/7e19cd5486b5d6dc1ef90e671ba52ae0?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
"id": 865,
"url": "https://api.github.com/users/pengwynn"
},
"closed_at": null,
"updated_at": "2012-11-14T15:25:33Z",
"number": 17,
"closed_by": null,
"html_url": "https://github.com/pengwynn/api-sandbox/issues/17",
"labels": [
{
"color": "ededed",
"name": "design",
"url": "https://api.github.com/repos/pengwynn/api-sandbox/labels/design"
}
],
"id": 8356941,
"assignee": null,
"state": "open",
"url": "https://api.github.com/repos/pengwynn/api-sandbox/issues/17"
}
Эти ссылки помогают потребителям нашего API в дальнейшем изучении ресурсов API. Например, если вам нужен аватар пользователя, вам действительно не нужно обращаться к документации. Его URI уже присутствует в ответе, вам просто нужно использовать этот URI и получить изображение.
9) Управление версиями
Всякий раз, когда вам нужно изменить структуру запроса или ответа, всегда есть шанс, что вы что-то сломаете для какого-то клиента. В таких случаях управление версиями может быть спасением. Все изменения в запросе и ответе должны создаваться как отдельная версия для API. Все потребители вашего API могут постепенно перейти на более новую версию вашего API. Управление версиями - гораздо лучший подход, чем принуждение всех потребителей одновременно переходить на новую версию вашего API.
Есть много способов реализовать версию, наиболее популярным из которых является поддержка версии в самих конечных точках. Например, в конечной точке ниже V1 - это версия вашего API.
http://localhost:8081/v1/blogs/1/comments/
Когда мы поддерживаем версию в конечной точке REST API, это может усложнить реализацию HATEOAS, поскольку вам придется добавить версию для всех ресурсов в ответ. Версия также может быть передана в строке запроса или даже путем создания нового настраиваемого заголовка Rest API. Опять же, оба этих подхода также страдают, поскольку они усложняют реализацию HATEOAS.
Один из подходов, более дружественный к HATEOAS, - это передача информации о версии в заголовке Accept, как показано ниже:
GET https://localhost:8081/blogs/3 HTTP/1.1 Accept: application/vnd.medium.v1+json
Выше мы говорим серверу, что клиентам нужна версия 1 нашего API, и ответ должен быть в формате JSON. Сервер сделает все возможное, чтобы удовлетворить эти требования и предоставить ответ.
При выборе правильного подхода к управлению версиями для вашей организации вам также следует рассмотреть возможность кэширования. Управление версиями с помощью URI и строки запроса более дружественно к кешированию, чем два других подхода. Для пользовательского заголовка и заголовка клиента вам может потребоваться написать дополнительный код для реализации кэширования.
Заключение
Rest API на первый взгляд кажется очень простым, но создание идеального Rest API может оказаться довольно сложной задачей. Для разработки Rest API нужно так много всего. Настоятельно рекомендуется потратить свое время и усилия на разработку своего API в первый раз, чтобы вам приходилось тратить меньше времени на переработку API в будущем.
Если у вас есть сомнения, не стесняйтесь комментировать эту статью.
ИСПОЛЬЗОВАННАЯ ЛИТЕРАТУРА
Больше контента на plainenglish.io
