Студия Михаила Кечинова

info@mkechinov.ru

ruen
Навигация
Главная Разработка API для веба

Разработка API для веба

Перспектива

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

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

Еще особенности разработки API. Разработчики обычно фокусируются на таких вопросах, как “что этот сервис должен делать?”, в то время как пользователей API интересует “как я могу потратить минимум усилий, чтобы получить от этого API то, что мне нужно”.

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

Итак, пять золотых правил для разработки хорошего API:

  1. Документация.

  2. Стабильность и последовательность.

  3. Гибкость.

  4. Безопасность.

  5. Простота адаптации.

Правило 1. Документация

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

Как писать хорошую документацию? Часть ее содержится в описаниях методов, например, запросов и ответов. Но что отличает хорошую документацию от просто вменяемой — это наличие примеров, а в идеале обучающих материалов.

Например, разработчики из Twilio перечислили каждый класс, метод и каждый возможный запрос к их API, но не удосужились упомянуть, что с помощью их API вы можете отправлять SMS, отслеживать звонки или даже купить телефонный номер. Сколько времени у программиста уйдет на то, чтобы до этого докопаться самостоятельно? Представьте гигантское дерево классов и методов без малейшего намека на то, как всем этим пользоваться. Звучит жутко? Тем не менее, именно так все обстоит у Rackspace CloudFiles, в API невозможно разобраться, если вы не работали с ним.

В общем, пишите подробную документацию с примерами и обучалками. А когда напишете — тестируйте на других. Рекомендуем дать им документацию и попросить сделать с помощью API что-нибудь совсем базовое за 15 минут. Если за это время у них ничего не получилось — дорабатывайте документацию.

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

Правило 2. Стабильность и последовательность

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

Вероятно, у вас нет такой шикарной пользовательской базы, поэтому ваш API должен быть более дружелюбным. Например, поддерживать старые версии API (возможно, годами). Здесь тоже есть несколько советов.

Давайте представим, что ваш API доступен по ссылке http://myapisite.com/api/widgets и он возвращает ответ в JSON-формате. На первый взгляд, все в порядке. Но что произойдет, если вам понадобится изменить формат JSON-ответа? Все проекты, которые уже пользуются вашим API, лягут. Упс.

Так что планируйте это наперед: включите номер версии в адрес ссылки на API, например, http://myapisite.com/api/widgets?version=1 или http://myapisite.com/api/widgets/v1. Сделайте так, чтобы люди смогли перейти на новую версию API, когда они будут к этому готовы. Если по какой-то причине вам нужно полностью отказаться от старой версии, делайте это, но предусмотрите следующее:

  • Разошлите предупреждение об этом заранее.

  • Предложите план по переходу на новую версию API.

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

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

Правило 3. Гибкость

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

Но, конечно, в гибкости тоже нужен баланс. Невозможно предусмотреть все способы, которыми ваш API будут использовать другие разработчики. Как и невозможно удовлетворять требованиям всех платформ (не все одинаково хорошо поддерживают JSON или OAuth).

Итак, многие API поддерживают различные форматы вывода данных: JSON, YAML, XML и т.д., но только некоторые указывают формат в ссылке (например, /api/v1/widgets.json или через ?format=JSON). Кстати, не забудьте сделать ссылку нечувствительной к регистру, чтобы ссылка вида ?format=json тоже срабатывала.

Еще совет: предусмотрите различные способы ввода переменных. У вас множество форматов на выходе, на входе должно быть то же самое (простые POST-переменные, JSON, XML и т.д.). Можете начать с поддержки POST и JSON как самых популярных.

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

Правило 4. Безопасность

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

В большинстве API используется простая аутентификация по токену, где токен — случайный хэш, присвоенный пользователю, который он может сбросить в любой момент. Убедитесь, что токен может быть передан через POST или HTTP-заголовок. Например, пользователь может передать SHA-1 токен как POST-переменную или как заголовок в формате “Authorization: da39a3ee5e6b4b0d3255bfef95601890afd80709”.

Также выберите безопасный токен, а не короткий числовой идентификатор. Например, сгенерируйте SHA-токен во время создания пользователя и сохраните его в базе. Затем просто просматривайте базу на наличие пользователя с совпадающим токеном. Также можете сделать генерируемый токен, состоящий из уникального идентификатора и независимой части, что-то наподобие SHA(User.ID + "abcd123").

Другой способ — использовать связку OAuth 2 + SSL. SSL вы будете использовать в любом случае, а OAuth 2 достаточно прост для внедрения в серверную часть, а его библиотеки доступны для большинства популярных языков.

Если ваша задача: разработка API, доступного на публичном веб-сайте через JavaScript, учитывайте следующее:

  • “Белые списки”. API позволяет проводит базовые операции: создавать, считывать, обновлять и удалять данные. Наверняка, вы не хотите, чтобы полный список действий был доступен всем без исключения. Поэтому уделите время созданию “уайтлиста” доступных действий. Например, убедитесь, что только авторизованные пользователи могут выполнять команды /user/delete. Аналогично проверяйте заголовки перед отправкой (если пользователю недоступен какой-либо контент — отправляйте 406 ошибку). Можете также использовать “черные списки” действий, которые вы не хотите разрешать пользователям вашего API.

  • Защитите себя от межсайтовой подделки запроса (CSRF). Если вы разрешаете аутентификацию сессии или кукис, вы должны убедиться, что ваш API устойчив к CSRF-атакам. Прочитайте руководство от Owasp.

  • Проверяйте доступ к ресурсам. При каждом запросе нужно проверять, есть ли у пользователя доступ к запрашиваемым данным. Например, если пользователь запрашивает данные кредитной карты /account/card/view/152423, убедитесь, что пользователь авторизован и действительно имеет ID “152423”.

  • Проверяйте ввод данных. Все данные должны быть тщательно проанализированы, предпочтительно с использованием хорошо известной библиотеки (если у вас ввод данных по JSON или XML). Только не пишите свой собственный парсер.

Правило 5. Простота адаптации

Вот несколько советов, которые помогут другим разработчикам выбрать именно ваш API:

  • Убедитесь, что люди действительно могут пользоваться вашим API (как в первый раз, так и постоянно).

  • Сохраняйте простоту. Не делайте сложную аутентификацию или собственные схемы генерации URL. Не переизобретайте SOAP или JSON, или REST, или что-то еще. Используйте как можно больше общепринятых популярных инструментов (чтобы разработчики изучали только ваш API, а не API + еще 10 незнакомых технологий).

  • Предоставляйте возможность работать с библиотеками для отдельных языков. Есть несколько хороших инструментов для автоматической генерации библиотек (такие, как Alpaca или Apache Thrift). Так Alpaca поддерживает Node, PHP, Python, and Ruby. Thrift supports C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi и много других языков.

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

  • Занимайтесь поддержкой. Большой барьер для адаптации к новому API — отсутствие поддержки. Вопросов у пользователей будет много: кто-то не поймет вот эту часть документации, кто-то напишет баг-репорт, а кто-то просто новичок и у него масса вопросов. Форумы, баг-трекеры, почты поддержки — это, конечно, для многих фантастика, но хотя бы убедитесь, что когда пользователь пишет о багах, вы получаете эти сообщения. Никто не хочет видеть пустующий форум или большой список багов, на который авторы API никак не прореагировали.

Разработка API: итоги

Веб-сервисов и из API предостаточно. Но, к сожалению, подавляющее большинство трудно использовать. Причины: скудная документация, неучтенные баги — да всё, что было названо выше.

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

Минутка ненавязчивой рекламы: мы делаем API для веб-сервисов и мобильных приложений на заказ. Делали и будем делать. Хотите, чтобы у вас был не просто хорошо написанный API, а тот самый, о котором шла речь в тексте выше — пишите. И вообще любые вопросы можете присылать на почту info@mkechinov.ru, мы подскажем и поможем определиться.

Почта: