Руководство для начинающих по API, протоколам и форматам данных

Что такое API, как они работают и как их использовать

API (интерфейс прикладного программирования) — это интерфейс между двумя приложениями, который позволяет им взаимодействовать друг с другом.

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

Итак, до сих пор у нас есть:

  • Интерфейс,
  • не менее двух приложений
  • и хотя бы одну программу с набором правил

Связь между приложениями не может происходить, пока одно из них не инициирует это, как в реальной жизни.

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

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

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

Однако, когда этот обмен осуществляется по сети, API называется веб-службой.

Вот практический пример. Когда вы ищете рейс в таком приложении, как Expedia, веб-приложение возвращает все доступные рейсы в указанный пункт назначения.

Он делает это посредством общения с другими приложениями, которые являются веб-сайтами различных авиакомпаний. Из этих других приложений Expedia может получать только определенные данные, поскольку веб-сайты авиакомпаний разрешают доступ только к определенным частям своих баз данных.

Таким образом, Expedia может показать вам в результате вашего поискового запроса, какие есть доступные рейсы, но не может показать вам, кто зарезервировал бизнес-места на рейс, который вы хотите забронировать.

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

Протоколы веб-API

Как упоминалось ранее, каждое приложение определяет свои собственные правила и протоколы связи.

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

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

Обе стороны — в данном случае бронирование и веб-сайт отеля — должны понимать и использовать один и тот же протокол и правила.

Вот еще один пример: представьте, что вы идете в ресторан в вашем районе и просите официанта принести вам билет на концерт вместо блюда из их меню.

См. также:  Интернационализация Flutter (i18n) 101

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

Точно так же, если вы попытаетесь заказать блюдо на иностранном языке, официант не сможет выполнить ваш запрос, потому что вы не будете использовать тот формат (язык), который вы ожидается использовать.

У нас есть две новые концепции:

  • протокол
  • формат

Протокол — это набор правил, которые определяют, как приложения могут взаимодействовать друг с другом, а формат определяет, как данные могут быть отправлены и доступны другим приложениям.

Наиболее используемый протокол — HTTP, что означает протокол передачи гипертекста, но SOAP, REST и XML-RPC также могут использоваться в качестве средств связи.

Протокол HTTP

HTTP — это протокол, используемый веб-браузерами, называемыми клиентами, для связи с веб-серверами.

Данные, которыми обмениваются две стороны, представляют собой не простые файлы, как в FTP (протокол передачи файлов), а гипертексты, записанные в формате HTML, которые передаются через Интернет.

Вот как выглядит этот процесс:

  1. запрос в этом случае отправляется браузером и включает в себя метод запроса, URI и версию протокола, а также другую информацию.
  2. Сервер получает запрос и запускает программу для его обработки.
  3. Сервер возвращает браузеру ответ HTTP.

Любой HTTP-запрос включает в себя начальную строку, которая инициирует запрос и сообщает программе, что делать, и заголовки, но это необязательно. Эти части тоже присутствуют в ответе, так что давайте посмотрим, что они означают.

В запросе в стартовой строке упоминается:

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

Существует четыре основных типа методов:

  • GET — это означает, что вы хотите получить данные из второго приложения.
  • POST — вы хотите создать информацию и добавить ее во второе приложение
  • PUT — вы хотите изменить данные во втором приложении
  • УДАЛИТЬ — вы хотите удалить информацию из второго приложения.

В ответе стартовая строка включает:

  • версия HTTP,
  • код состояния, который сообщает вам, сработала ли транзакция API
  • папки и параметры, указывающие, где искать данные и что именно искать

Коды ответа / состояния сгруппированы в пять классов:

  • информационные ответы (_1 _ – _ 2_)
  • успешные ответы (_3 _ – _ 4_)
  • перенаправления (_5 _ – _ 6_)
  • клиентские ошибки (_7 _ – _ 8_)
  • ошибки сервера (_9 _ – _ 10_)

Заголовки представляют собой набор key: value пар, которые используются для передачи заранее определенной информации серверу, чтобы сервер мог понять, что мы хотим.

Примером заголовка запроса является хост, который используется для указания интернет-хоста запрашиваемого ресурса. Например, в случае Medium хостом будет www.medium.com.

См. также:  Я не могу с тобой больше согласиться. И все же это часто вызывает споры!

Примером заголовка ответа являются файлы cookie, используемые веб-сайтом, на котором мы запрашиваем информацию.

Помимо начальной строки и заголовка, HTTP-запрос также включает тело, содержание которого зависит от используемого метода. Например, в случае GET мы хотим получить данные, поэтому тело ничего не содержит.

С другой стороны, если мы используем метод POST, мы создаем информацию, например имя пользователя. Эту информацию необходимо передать второму приложению в поле тела HTTP-запроса.

Форматы для получения данных: JSON и XML

Веб-API обычно отправляют HTTP-запросы и получают данные в форме ответа JSON или XML.

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

Формат XML

XML — это аббревиатура от eXtensinble Markup Language, он похож на HTML, являясь самоописательным языком. Его роль заключается в хранении и транспортировке данных.

Однако, в отличие от HTML, XML ничего не делает с данными. Он его не меняет и не отображает. Теги XML не определены заранее, поэтому вы можете заключать свой контент и данные в любые теги, какие захотите.

Например:

<summary>
  <title>Book title</title>
  <author>Author name</author>
  <reviewer>Reviewer name</reviewer>
  <note>Note left by reviewer</note>
</summary>

Приведенные выше теги сами по себе ничего не значат, но они помогают легко интерпретировать полученные данные.

Кроме того, XML является расширяемым, что означает, что даже если вы добавите новые теги позже, предыдущая версия приложения не пострадает, она все равно будет работать.

Большинство веб-браузеров имеют встроенный объект XMLHttpRequest, который позволяет запрашивать данные с сервера. Это делает формат XML очень удобным при обмене данными.

Формат JSON

JSON похож на XML в том смысле, что он хранит и передает данные. Однако синтаксис другой, так как вместо тегов у нас key:value пар. Вот как выглядит файл JSON:

{"Summary" : [
  {"Title": "Book title", 
   "Author": "Author name",
   "Reviewer": "Reviewer name",
   "Note": "Note left by reviewer"
  }
 ]
}

Аббревиатура происходит от нотации объектов JavaScript, поэтому этот код выглядит как объект JS.

JSON проще, проще в использовании и меньше по размеру, поэтому предпочтительно использовать этот формат вместо XML.

REST и SOAP API

И REST, и SOAP используют HTTP для отправки запросов и получения ответов, но хотя SOAP является протоколом, REST является архитектурным шаблоном. Запросы REST API очень похожи на запросы браузера, описанные ранее.

В архитектуре REST клиент отправляет запрос на получение или изменение ресурса, а сервер отправляет ответ на запрос. SOAP полагается исключительно на XML, в то время как REST использует JSON. Это означает, что REST легче и проще в использовании.

См. также:  ReflexJS для внешнего интерфейса

Вот как может выглядеть простой запрос SOAP:

<?xml version="1.0"?>

<soap:Envelope
xmlns:soap="https://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="https://www.w3.org/2003/05/soap-encoding">

<soap:Body>
  <m:GetPrice xmlns:m="https://www.w3schools.com/prices">
    <m:Item>Apples</m:Item>
  </m:GetPrice>
</soap:Body>

</soap:Envelope>

Для сравнения, вот как может выглядеть REST-запрос:

curl -X GET "https://api.fungenerators.com/fact/random?category=Countries&subcategory=USA" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

REST происходит от REpresentational State Transfer, и, как следует из его названия, этот протокол позволяет передавать состояние ресурса. Состояние — это моментальный снимок этого ресурса, например веб-страницы, в определенный момент времени.

Запрос REST состоит из:

  • конечная точка
  • метод
  • заголовки
  • тело (данные)

Конечная точка или маршрут — это URL-адрес, с которого вы запрашиваете, или начальная точка API-интерфейсов, с которых вы запрашиваете данные. Например, https://api.github.com или https://api.fungenerators.com являются конечными корневыми точками.

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

После пути можно указать параметры, например:

https://api.fungenerators.com/fact/random?category=Countries&subcategory=USA

Параметры всегда следуют после знака ?.

Это означает, что из конечной точки выше мы хотим получить только данные в категории Countries, а из этой категории только подкатегорию USA. Параметры также будут упомянуты в документации API.

Переходя к методам, которые вы можете использовать в REST API, мы уже обсуждали их ранее: получение, публикация, размещение и удаление. Например, если мы хотим добавить случайный факт в API, который мы используем выше, мы можем использовать метод PUT:

curl -X PUT "https://api.fungenerators.com/fact?fact=some%20random%20fact.&category=Numbers&subcategory=Date&tags=numbers%2C%20historical" -H  "accept: application/json" -H  "X-Fungenerators-Api-Secret: api_key"

Вы можете поиграть с этим REST API здесь: https://fungenerators.com/api/facts/, или вы можете получить доступ к полному списку общедоступных API здесь: https://github.com/public-apis/public -апись .

Конечно, в приложении данные, которые вы запрашиваете или обновляете, должны иметь смысл.

Например, предположим, что вы создаете приложение, которое рекомендует каждую неделю читать новую книгу. Для этого вы можете использовать Good Reads API и так далее.

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

Если вам интересно узнать больше, есть несколько действительно хороших статей, которые научат вас создавать REST API:

 

Вот как легко создать REST API
Узнайте, как быстро создать семантический REST API с помощью Python Flask codeburst.io

 

 

Создание простого REST API с помощью NodeJS и Express.
Работали ли вы над интерфейсными технологиями и чувствовали, что что-то упускаете в целом… medium.com

 

Понравилась статья? Поделиться с друзьями:
IT Шеф
Добавить комментарий

;-) :| :x :twisted: :smile: :shock: :sad: :roll: :razz: :oops: :o :mrgreen: :lol: :idea: :grin: :evil: :cry: :cool: :arrow: :???: :?: :!: