5 золотых правил отличного дизайна веб-API

Вы когда-нибудь задавались вопросом : «О чем они думали?» при интеграции веб-сервиса через его API? Если нет, то вам повезло больше, чем мне.

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

Перспектива

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

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

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

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

Разработчики API обычно сосредотачиваются на таких вопросах, как «Что должен делать этот сервис?» или «Что должна предоставлять эта услуга?» , в то время как пользователи API сосредоточены на том, «Как я могу использовать этот API, чтобы делать то, что мне нужно?» , или, точнее, «Как я могу приложить минимум усилий, чтобы получить от этого API то, что мне нужно?» .

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

Хотя это может показаться простым и очевидным, поразительно, как редко API разрабатываются таким образом. Подумайте об API, с которыми вы сталкивались в своей карьере. Как часто кажется, что они были разработаны с учетом этой точки зрения? Дизайн веб-API может быть сложным.

Итак, с учетом сказанного, давайте продолжим и поговорим о 5 золотых правилах проектирования отличного веб-API , а именно:

1. Документация
2. Стабильность и последовательность
3. Гибкость
4. Безопасность
5. Простота принятия

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

Документация. Да, я начинаю здесь.

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

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

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

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

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

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

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

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

Некоторые заслуживающие внимания примеры отличной и подробной документации можно найти в Twilio, Django и MailChimp. Ни один из этих продуктов не обязательно является лучшим на своих рынках (хотя все они являются хорошими продуктами), тем не менее, они отличаются тем, что предоставляют лучшую документацию на своих рынках, что, безусловно, способствовало их широкому признанию и доле на рынке.

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

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

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

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

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

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

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

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

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

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

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

Например, многие API будут поддерживать различные форматы вывода, такие как JSON, YAML, XML и т. д. al., но будет поддерживать указание формата только в самом URL. В духе сохранения гибкости вы можете разрешить это также указывать в URL-адресе (например, /api/v1/widgets.json ), или вы также можете прочитать и распознать HTTP-заголовок Accept: application/json или поддерживать переменная строки запроса, например ?format=JSON и т. д.

И пока мы на этом, почему бы не сделать указанный формат нечувствительным к регистру, чтобы пользователь мог также указать ?format=json ? Это классический пример того, как облегчить ненужное разочарование пользователя вашего API.

Другой пример позволяет использовать различные способы ввода переменных. Таким образом, точно так же, как у вас есть различные форматы вывода, допускайте также различные форматы ввода (например, простые переменные POST, JSON, XML и т. д.). Вы должны, по крайней мере, поддерживать стандартные переменные POST, и многие современные приложения также поддерживают JSON, так что эти два — хорошее место для начала.

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

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

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

Для большинства API я предпочитаю простую аутентификацию на основе токенов, где токен представляет собой случайный хэш, назначенный пользователю, и он может сбросить его в любой момент, если он был украден. Разрешить передачу токена через POST или HTTP-заголовок. Например, пользователь может (и должен) отправить токен SHA-1 в виде переменной POST или в виде заголовка в таком формате, как «Авторизация: da39a3ee5e6b4b0d3255bfef95601890afd80709».

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

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

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

Вот некоторые другие важные вещи, о которых следует помнить:

• Функциональность белого списка. API обычно позволяют выполнять базовые операции создания, чтения, обновления и удаления данных. Но вы не хотите разрешать эти операции для каждого объекта, поэтому убедитесь, что у каждого есть белый список разрешенных действий. Убедитесь, например, что только авторизованные пользователи могут запускать такие команды, как /user/delete/<id> . Точно так же все полезные заголовки, которые отправляются в запросе пользователя, также должны быть проверены по белому списку. Если вы разрешаете заголовки Content-type, убедитесь, что все, что отправляет пользователь, действительно соответствует списку поддерживаемых типов контента. Если это не так, отправьте обратно сообщение об ошибке, например ответ 406 Not Acceptable. Белый список важен, поскольку многие API-интерфейсы генерируются автоматически или вместо этого используют черный список, а это означает, что вы должны четко указать, чего вы не хотите. Однако золотое правило безопасности заключается в том, чтобы начинать абсолютно ни с чего и явно разрешать только то, что вам действительно нужно.

• Защитите себя от подделки межсайтовых запросов (CSRF). Если вы разрешаете аутентификацию сеанса или файлов cookie, вам необходимо убедиться, что вы защищаете себя от атак CSRF. Проект Open Web Application Security Project (OWASP) предоставляет полезные рекомендации по предотвращению этих уязвимостей.

• Подтвердите доступ к ресурсам. В каждом запросе вам необходимо убедиться, что пользователю действительно разрешен доступ к конкретному элементу, на который он ссылается. Таким образом, если у вас есть конечная точка для просмотра сведений о кредитной карте пользователя (например, /account/card/view/152423 ), убедитесь, что идентификатор «152423» ссылается на ресурс, к которому у пользователя действительно есть доступ.

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

Правило 5: Простота принятия

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

Вот несколько конкретных рекомендаций, которые упростят и упростят внедрение вашего API:

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

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

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

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

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

Подведение итогов веб-API

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

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