Введение в REST API

Что такое REST API с точки зрения создателя REST API и с точки зрения потребителя

API означает интерфейс прикладного программирования, и это общий термин, обозначающий разные вещи.

Мы увидели, как браузер может предлагать некоторые API в виде доступных нам функций.

Мы видели, как Node.js предлагает нам программный API с модулями по умолчанию.

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

Вообще говоря, в настоящее время у нас есть 2 категории API-интерфейсов: API-интерфейсы REST и API-интерфейсы GraphQL.

Существуют и другие виды парадигм API, например SOAP, но они не очень популярны в мире JavaScript.

В этом посте мы поговорим о REST API.

Конечные точки

В REST API мы создаем рядконечные точкичто клиент может получить доступ.

Допустим, мы хотим показать список людей. Мы можем создать конечную точку, которая будет реагировать на/people маршрут.

Если наш сервис прослушивает доменtest.com, у нас будетtest.com/peopleURL.

Эта конечная точка будет предоставлять данные в любом формате, но обычно мы используемJSON, удобный текстовый формат, используемый для обмена данными между двумя службами.

Этот/peopleконечная точка может предоставить список имен людей, аidдля каждого человека. Это может бытьidкоторые мы используем, например, для их хранения в базе данных.

Наша система также может предоставить другую конечную точку, которую мы можем назвать/person. Это принимаетidкоторый однозначно идентифицирует человека, например:/person/1

Наш API предоставит дополнительную информацию об этом человеке, например возраст, адрес электронной почты, адрес.

Важно отметить, что в первой конечной точке у нас не было никакого параметра, но на этот раз он у нас есть.

Параметры можно отправлять по-разному, и не все конечные точки будут использоваться для отправки информации с сервера. Как мы скоро увидим, для выполнения действий будут использоваться некоторые другие конечные точки.

Методы

Я упомянул, что/peopleendpoint вернет список людей в нашей системе.

Это было упрощением, и пора копнуть глубже.

REST API использует принципы протокола HTTP для предоставления различных функций в зависимости отHTTP методиспользовал:GET,POST,PUT,DELETE.

GETсамый распространенный. Когда клиент вызывает нашу конечную точку API с помощью метода GET, он сигнализирует, что хочет прочитать данные.

GET /peopleвернет список людей.

GET /person/1вернет детали человека.

Когда метод HTTPPOST, смысл совсем другой. Конечная точка будет такой же, но требуемое действие будет другим.

Мы, как разработчики API, определяем его значение.

Например, мы могли бы создатьPOST /personконечная точка, которая при вызове создает нового человека в базе данных.

Он получает данные от клиента в заранее определенном формате, который мы можем выбрать. Скоро мы увидим пример, сделанный с использованием Express.

GETиPOSTявляются основными используемыми 2 глаголами.

Иногда мы используемPUTиDELETE:PUTиногда используется для обновления ресурса, например, для изменения адреса человека.DELETEиспользуется для удаления ресурса.

В других случаях,POSTиспользуется для всего, что не читает, гдеGETиспользуется.

У нас есть свобода выбора.

Под ресурсом мы понимаем сущность, как и люди во множественном числе в случае/people, или один человек в случае/person.

Именование конечных точек API

Посмотри, как я использовал/peopleи/personнад.

Этосуществительные.

Использование существительных для конечных точек и использование HTTP-методов для сигнализации о действии считается лучшей практикой.

Обновление человека используетPOSTзапрос в/personконечная точка.

Если вы хотите создать API для отправки сообщения человеку, вы должны сделатьPOSTзапрос с использованием/messageконечная точка, передавая ей данные для идентификации человека и сообщения, которое вы хотите отправить.

REST API не имеет состояния

REST API не имеет состояния.

Это означает, что у него нет памяти между разными запросами.

Большинство API-интерфейсов, которые вы можете найти, реализуют механизм API-ключа, который служит способом отслеживать, кто вызывает API, и предоставляет способ мониторинга использования и принудительных ограничений.

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

Ответы

Вызов API вернет ответ пользователю в двух формах: код состояния ответа HTTP и тело ответа HTTP.

Каждый HTTP-запрос имеет код состояния.

У нас есть некоторые соглашения относительно кода состояния HTTP-ответа: когда вы используете браузер для открытия веб-страницы, страница будет возвращать200 OKкод состояния. Если страница не найдена,404 NOT FOUNDкод состояния.

То же самое и с нашими API.

Общие из них:

  • 200 OK: это стандартный ответ для успешных HTTP-запросов.
  • 201 Created: Обычно это ответ на запрос POST. Запрос был выполнен, и новый ресурс был создан.
  • 400 Bad RequestИз-за ошибки запроса, сгенерированной на клиенте, сервер не может обработать запрос. Ошибки могут включать в себя неправильный запрос, слишком большой размер для обработки и другие.
  • 401 UnauthorizedОтправляется, когда требуется аутентификация и клиент не авторизован
  • 403 ForbiddenРесурс недоступен по разным причинам. Если причина в аутентификации, предпочтительнее использовать код статуса 401 Unauthorized.
  • 404 Not FoundЗапрошенный ресурс не может быть найден.
  • 405 Method Not AllowedРесурс недоступен с помощью этого метода HTTP, но может быть с другим.
  • 500 Internal Server ErrorОбщее сообщение об ошибке сервера, которое выдается, когда возникла непредвиденная ситуация, и более конкретное сообщение не подходит.

Вы можете найти полный список наСписок кодов состояния HTTP. Следует отметить, что при создании API вы всегда должны возвращать правильный код состояния, чтобы информировать своих клиентов.

Тело ответа обычно представляет собой ответ JSON с запрошенными данными или сообщение об ошибке.

Детали того, как создается сообщение, решаются вами, разработчиком API, или тем, кто создал этот API.


Дополнительные уроки по сети: