Не существует единого подхода к разработке API или даже к тому, как «правильно» как работать с API. Вместо этого, нам нужно опираться на отраслевые основные рекомендации по проектированию, лучшие практики и шаблоны. В блоге студии web-разработки YuSMP Group разобрались с понятием, назначения и правилами проектирования API.

иллюстрация: qatestlab

Что такое API, виды и назначение

API-интерфейсы стали наиболее распространенным способом взаимодействия программ и устройств друг с другом в современных вычислениях. 

Web API — это набор правил, описывающих, как одна программа может подключиться и взаимодействовать с другой. Для чего и как использовать API: эти конструкции нужны для облегчения процесса программирования. Application Programming Interfaces уже содержат сложную часть кода, которую нужно только внедрить.

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

REST API

REST API — это подход, фундаментальной концепцией которого является ресурс. Ресурс — это объект с типом, связанными данными, отношениями с другими ресурсами и набором методов, которые с ним работают. Это очень похоже на идею объектов в программировании, хотя определено только несколько стандартных методов, типичных для HTTP GET, POST, PUT и DELETE. Ресурсы могут существовать сами по себе или быть сгруппированы в коллекции, которые сами являются ресурсами.

В современных вычислениях общая модель — также фундаментальная для REST API — является клиент серверное взаимодействие. Когда клиент, которому нужен ресурс, идентифицирует и связывается с серверной частью сайта. Практически весь облачный трафик управляется таким образом, поскольку он обеспечивает максимальную гибкость. Этот принцип также хорошо работает для так называемых «бессерверных» архитектур приложений, где сервис-брокер занимает место сервера, известного клиенту.

Шесть правил проектирования REST API

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

1. Единый интерфейс

Все запросы, сделанные через REST API, должны соответствовать правилам форматирования этого API. Независимо от того, какой клиент делает запрос, он должен поместить каждую часть информации туда, где ее поместил бы любой другой клиент. Одним из примеров является URL-адрес или унифицированный указатель ресурса, используемый для идентификации ресурсов через HTTP, который является одним из примеров универсального идентификатора ресурса (URI), который может иметь более широкие области действия.

2. Разделение клиент-сервер

API REST требуют, чтобы клиент, серверное приложения были полностью независимы друг от друга. Клиенту нужно знать только полное имя ресурса, который ему нужен в виртуальном пространстве, разрешенном API. В противном случае единственными знаниями клиента и сервера друг о друге являются данные, которыми обмениваются транзакции API.

3. Безгражданство

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

4. Кэшируемость

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

5. Многоуровневая системная архитектура

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

6. Код по запросу

Хотя API-интерфейсы REST могут и часто предоставляют только данные для потребления клиентом, все чаще код доставляется для запуска на клиент-сервере Java, клиент-сервере Android или веб-приложении Javascript. Если это реализовано, то такой код может быть запущен только по требованию клиента.

Как работают API REST

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

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

API-интерфейсы REST передают всю эту информацию через комбинацию заголовков и полей параметров и могут обмениваться фактическими данными в любом формате. Очень распространенным стандартом является JSON, формат нотации объектов Javascript, который, несмотря на свое название, читается как людьми, так и машинами, на глаз или с использованием любого из популярных языков программирования.

При проектировании REST API необходимо учитывать эффективность, особенно там, где необходимо обрабатывать большие объемы данных или потоки, критичные ко времени, или, наоборот, небольшие объемы данных из источников с ограниченными ресурсами, таких как системы IoT.

Резюме

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