5 шагов к созданию успешного API

Это природа разработки программного обеспечения. Разработчики создают программное обеспечение с учетом потребностей конечного пользователя. Это кажется довольно простым, но иногда эти пользователи также являются коллегами-разработчиками. Им не нужны вещи, разбитые на них. Им даже не нужна простота. Все, что им нужно, - это доступ - способ интеграции вашего программного обеспечения с их. Вот тут и появляется API (интерфейс прикладного программирования). Я надеюсь выделить пять шагов, которые вы можете предпринять, чтобы создать успешный API.

Делай свою домашнюю работу

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

Существует множество различных технологий, но большинство API, которые вы увидите, будут использовать либо интерфейс RESTful, либо SOAP. Если вы не знаете, какой API-интерфейс вы собираетесь использовать, я бы предложил использовать подход RESTful, использующий протокол HTTP. Он проще, чем SOAP, в настоящее время он более популярен, и с ним будет легче начать работу при использовании программного продукта на основе Интернета.

Быть последовательным

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

При использовании подхода RESTful существует много разных схем именования URI. У каждого есть свои сторонники, так что просто выберите один и придерживайтесь его. То же самое касается структуры ввода и вывода. Большинство API поддерживают использование XML и JSON в качестве форматов ввода и вывода. Я бы предложил поддержать оба варианта, но выбрать формат по умолчанию.

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

Обычной практикой является включение какого-либо флага состояния в выходные данные, которые вы отправляете обратно клиенту. При использовании подхода RESTful API это должно быть сделано с использованием кодов состояния HTTP. Например, если вы только что обработали запрос PUT для существующего объекта данных, код состояния HTTP, который вы включаете в свой ответ, будет различаться в зависимости от результата запроса.

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

Используйте OAuth

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

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

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

Начать рано

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

Написать хорошую документацию

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

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

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

Разработка API: не усложняйте

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