При разработке API принято придерживаться стандарта REST.
REST (Representational State Transfer — «передача репрезентативного состояния» или «передача самоописываемого состояния») - архитектурный стиль взаимодействия компонентов распределенного приложения в сети. Другими словами, REST — это набор правил того, как программисту организовать написание кода серверного приложения, чтобы все системы легко обменивались данными и приложение можно было масштабировать.
При этом важно понимать, что REST сам по себе не является стандартом. Это может затруднить задачу создания интуитивно понятных API в стиле REST. Этот подход скорее представляет из себя способ мышления или искусство, нежели жесткий набор правил.
Существуют определенные аспекты, которые многие разработчики и компании осмысливают верно, и множество практик, которые многие применяют неверно.
Как же следует подходить к разработке интерфейсов API? Что делает API действительно качественным?
Необходимо быть последовательным
Прежде всего, вы разрабатываете интерфейс, который другие люди должны будут научиться использовать. Его будет проще освоить если весь интерфейс будет следовать единым правилам. Этот принцип применим к таким большим и важным аспектам, как распределение ресурсов, так и к самым мелким деталям, например наименование объектов.
Также важно иметь совместимость с другими API, с которыми разработчики уже знакомы. Это ускоряет освоение аналогичных API.
Однако даже при тщательно разработанном стандарте всегда найдутся исключения и уникальные ситуации. В этих случаях всегда полезно попробовать ответить на вопросы:
- Какие предыдущие практики были успешны?
- Если не было опыта в разработке успешных API, то какие методы используются в других API другими разработчиками? Какие подходы являются наиболее распространенными? Почему некоторые компании отклоняются от этих стандартов?
- Какие возможные сценарии использования могут появиться в будущем, когда потребуется что-то подобное? Какова ценность таких сценариев?
- Что является наиболее интуитивным и запутанным? Какие решения, по мнению других разработчиков, считаются наиболее простыми?
Наверняка перед разработкой вашего API у вас перед глазами есть несколько примеров хороших, общедоступных API, но несмотря на это вам необходимо создать API именно для вашего конкретного сценария!
Всё зависит от ресурсов
Ресурсы играют ключевую роль в архитектуре REST. REST API сосредоточено вокруг ресурсов. Вся концепция, лежащая в основе REST, заключается в том, что вы предоставляете доступ к ресурсам в Интернете. Вы позволяете выполнять операции над набором таких ресурсов.
Важно, чтобы эти ресурсы были полностью стабильными. Под стабильностью подразумевается, что каждый эндпоинт, возвращающий определенный ресурс, должен возвращать идентичное представление этого ресурса. Различные эндпоинты не должны возвращать разные наборы полей. Концепция этого ресурса всегда должна оставаться постоянной. Потребитель API не должен догадываться, какие поля будут возвращены из конкретного эндпоинта.
Единственный случай, когда можно вернуть не полное представление ресурса, - это, например, случай, когда ресурс содержит ссылку на другой ресурс (например, родительский объект). В этом случае допустимо предоставить минимальное представление ресурса, на который указывает ссылка. Это особенно важно в мультисервисной архитектуре, где служба API может не иметь полного контроля над всеми ресурсами, на которые есть ссылки. Минимальное представление должно содержать информацию, необходимую для идентификации ресурса (обычно это два поля: тип и идентификатор).
При разработке указанных ресурсов следует иметь в виду, что API ресурсы могут отличаться от объектов, присутствующих в базе данных. Проектировании API можно рассматривать как возможность пересмотреть структуру данных.
Естественно, что стоит избегать ситуации, когда для каждого вызова API требуется сделать множество сложных запросов к базе данных. Однако, при наличии осмысленной логики, имеет смысл переименовывать объекты и абстрагировать сложные концепции. Так, например, присутствие трех различных объектов в базе данных, представляющих статусы "приглашен", "подтвержден" или "заархивирован" для пользователя, не обязательно должно быть видимым на уровне потребителей API.
Если возникает впечатление, что на определенном ресурсе выполняются разнонаправленные действия, вероятно, происходит объединение элементов, которые должны оставаться отдельными ресурсами. Чем более модульной и структурированной будет архитектура, тем больше гибкости вы предоставите пользователям API. Это также упростит понимание процессов работы с ним.
Идентификаторы
Всегда используйте уникальные ID в своих API. Неизменно придерживайтесь принципа внедрения уникальных идентификаторов в ваши API. Все ресурсы, возвращаемые в ответе, должны содержать идентификатор.
Для всех эндпоинтов, использующих метод GET, является важным предоставить возможность извлечения ресурсов по их уникальному идентификатору (ID). В случае желания разрешить выборку ресурсов по альтернативным параметрам, таким как имя или какой-то другой атрибуты, необходимо внедрить фильтр запросов, для того чтобы не пропускать ID.
Помимо этого должна гарантироваться уникальность данного идентификатора. Важно отметить, что он не обязан быть уникальным на уровне всех ресурсов, однако он должен быть уникальным в пределах всех объектов определенного типа ресурсов. Даже после удаления и последующего запроса на извлечение ресурса, результатом всегда должен оставаться именно тот же ресурс.
Этот уникальный идентификатор не обязательно должен ограничиваться стандартным идентификатором базы данных; он может быть сформирован путем объединения или хэширования различных полей. Но самом деле, не имеет значения, каков идентификатор, пока он однозначно идентифицирует объект.
Имена ресурсов
Ресурсы играют ключевую роль в структуре API. Однако, если конечному пользователю будет непонятно, что они представляют, их использование может быть практически бесполезным. Названия ресурсов должны быть точными и однозначно указывать на их суть. Кроме того, они всегда должны использоваться во множественном числе, так как ресурсы представляют собой объекты, а объекты всегда имеют существительное форму, а не глагол.
Почему же всё таки во множественном числе? Почему лучше использовать множественное число для обозначения ресурсов в API? Эндпоинт не представляет один отдельный экземпляр ресурса, а скорее ссылается на пул всех ресурсов данного типа на сервере.
Для примера, рассмотрим эндпоинт /plants. Он представляет собой все растения на сервере. Запрос GET /plants должен возвращать список этих растений. А запрос POST /plants добавляет новый элемент в этот общий пул растений.
Даже если мы возьмем запрос GET /plants/{plantId}, который, как ожидается, вернет только один элемент (благодаря уникальному идентификатору), это будет по-прежнему означать выборку из общего списка растений. Таким образом, ресурсы всегда должны быть обозначены во множественном числе.
Итак, использование множественного числа для обозначения ресурсов в API позволяет легче управлять коллекциями ресурсов и выполнять различные операции над ними.
Следование стандартам
Несмотря, что у REST нет стандарта, он использует некоторые другие протоколы, у которых есть свои стандарты. Например, большинство разработчиков проектируют свои REST API, используя JSON и HTTP. Эти компоненты не являются обязательными, но оба, особенно HTTP, почти универсальны.
Если вы выбрали JSON и HTTP для своего API, важно придерживаться соответствующих стандартов. Стандарт JSON прост в использовании, а HTTP весьма обширен и включает в себя множество моментов. Важно обратить внимание на несколько ключевых аспектов, таких как корректное применение кодов состояния и правильное использование HTTP-методов. Соблюдение этих требований обязательно для создания высококачественного API.
Полнота
Люди часто рассматривают использование ссылок HATEAOS (Hypermedia as the Engine of Application State) как следующий этап развития REST или как истинный RESTful. Тем не менее, хотя идея ссылок HATEAOS хороша в своей концепции, они бесполезны для того, как большинство людей используют современные API. Поэтому к внедрение HATEAOS следует относится осторожно.
Однако, даже если вы не планируете внедрять ссылки HATEAOS, вы должны быть уверены, что пользователь может переходить от ресурса к ресурсу. Пользователи должны иметь возможность выполнять рабочие процессы исключительно через API. Это означает, что если есть ссылка на родительскую папку в файловом ресурсе, то также должен быть эндпоинт GET для извлечения этой родительской папки. Это еще раз подтверждает важность идентификаторов. При перечислении, к примеру, групп, связанных с пользователем, недостаточно предоставить только их имена. Обязательно следует включить идентификаторы, чтобы пользователи API имели возможность получить дополнительную информацию о группах или управлять ими. Пользователи должны иметь возможность легко перемещаться между ресурсами, используя предоставленные данные.
Большинство API-интерфейсов содержат некоторые проблемы и не соответствуют пользовательскому интерфейсу, однако желательно минимизировать пробелы там, где это выполнимо. Построение новых API-интерфейсов требует значительных затрат времени, поэтому в поиске оптимальных решений разумно рассмотреть возможность предоставления всех необходимых API-интерфейсов для данного ресурса, вместо добавления нескольких интерфейсов для различных ресурсов.
Отчасти прелесть API заключается в том, что они открывают функциональные возможности, о которых первоначальная компания даже не мечтала. Они позволяют разработчикам расширять функциональность за пределы вариантов использования, представленных в пользовательском интерфейсе, и создавать совершенно новые потоки. Исходя из этого, важно не только предоставлять API для известных вариантов использования, но и стремиться охватить максимальное количество API, начиная с ключевых компонентов.
Вывод
О REST говорят много, но реального стандарта нет, поэтому написать хорошие, удобные и расширяемые API может оказаться непросто. Чтобы проектирование давалось легко, может потребоваться время и практика, но есть определенные вещи, которые важно иметь в виду.
Ваши API можно улучшить, потратив время на тщательное продумывание ресурсов — всегда используя существительные во множественном числе, обязательно указывая тип и идентификатор, а также следуя соответствующим стандартам.
Также, можно облегчить задачу разработчикам в использовании вашего API, предоставив API для наибольшего возможного объема продукта. Наконец, прежде всего, согласованность вашего API и других API-интерфейсов сделает ваши API простыми в использовании.
