Разработка api что это
Что такое API
Содержание
— А зачем это мне? Я вообще-то web тестирую! Вот если пойду в автоматизацию, тогда да… Ну, еще это в enterprise тестируют, я слышал…
А вот и нет! Про API полезно знать любому тестировщику. Потому что по нему системы взаимодействуют между собой. И это взаимодействие вы видите каждый день даже на самых простых и захудалых сайтах.
Любая оплата идет через API платежной системы. Купил билет в кино? Маечку в онлайн-магазине? Книжку? Как только жмешь «оплатить», сайт соединяет тебя с платежной системой.
Но даже если у вас нет интеграции с другими системами, у вас всё равно есть API! Потому что система внутри себя тоже общается по api. И пока фронт-разработчик усиленно пилит GUI (графический интерфейс), вы можете:
Что такое API
API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».
Если переводить на русский, это было бы слово «договор». Договор между двумя сторонами, как договор на покупку машины:
API — набор функций
Когда вы покупаете машину, вы составляете договор, в котором прописываете все важные для вас пункты. Точно также и между программами должны составляться договоры. Они указывают, как к той или иной программе можно обращаться.
Соответственно, API отвечает на вопрос “Как ко мне, к моей системе можно обратиться?”, и включает в себя:
Тут вы можете мне сказать:
— Хмм, погоди. Операция, данные на входе, данные на выходе — как-то всё это очень сильно похоже на описание функции!
Если вы когда-то сталкивались с разработкой или просто изучали язык программирования, вы наверняка знаете, что такое функция. Фактически у нас есть данные на входе, есть данные на выходе, и некая магия, которая преобразует одно в другое.
И да! Вы будете правы в том, что определения похожи. Почему? Да потому что API — это набор функций. Это может быть одна функция, а может быть много.
Как составляется набор функций
Да без разницы как. Как разработчик захочет, так и сгруппирует. Например, можно группировать API по функционалу. То есть:
Можно не группировать вообще, а делать одно общее API.
Можно сделать одно общее API, а остальные «под заказ». Если у вас коробочный продукт, то в него обычно входит набор стандартных функций. А любые хотелки заказчиков выносятся отдельно.
Получается, что в нашей системе есть несколько разных API, на каждое из которых у нас написан контракт. В каждом контракте четко прописано, какие операции можно выполнять, какие функции там будут
И конечно, функции можно переиспользовать. То есть одну и ту же функцию можно включать в разные наборы, в разные апи. Никто этого не запрещает.
Получается, что разработчик придумывает, какое у него будет API. Либо делает общее, либо распределяет по функционалу или каким-то своим критериям, и в каждое апи добавляет тот набор функций, который ему необходим.
При чем тут слово «интерфейс»
— Минуточку, Оля! Ты же сама выше писала, что API — это Application programming interface. Почему ты тогда говоришь о контракте, хотя там слово интерфейс?
Да потому, что в программировании контракт — это и есть интерфейс. В классическом описании ООП (объектно-ориентированного программирования) есть 3 кита:
Не всегда программа предоставляет именно графический интерфейс. Это может быть SOAP, REST интерфейс, или другое API. Чтобы использовать этот интерфейс, вы должны понимать:
Как вызывается API
Вызвать апи можно как напрямую, так и косвенно.
Вызов API напрямую
1. Система вызывает функции внутри себя
Разные части программы как-то общаются между собой. Они делают это на программном уровне, то есть на уровне API!
Это самый «простой» в использовании способ, потому что автор API, которое вызывается — разработчик. И он же его потребитель! А значит, проблемы с неактуальной документацией нет =)
Шучу, проблемы с документацией есть всегда. Просто в этом случае в качестве документации будут комментарии в коде. А они, увы, тоже бывают неактуальны. Или разработчики разные, или один, но уже забыл, как делал исходное api и как оно должно работать…
2. Система вызывает метод другой системы
А вот это типичный кейс, которые тестируют тестировщики в интеграторах. Или тестировщики, которые проверяют интеграцию своей системы с чужой.
Одна система дергает через api какой-то метод другой системы. Она может попытаться получить данные из другой системы. Или наоборот, отправить данные в эту систему.
Допустим, я решила подключить подсказки из Дадаты к своему интернет-магазинчику, чтобы пользователь легко ввел адрес доставки.
Я подключаю подсказки по API. И теперь, когда пользователь начинает вводить адрес на моем сайте, он видит подсказки из Дадаты. Как это получается:
И, конечно, не забываем про кейс, когда мы разрабатываем именно API-метод. Который только через SOAP и можно вызвать, в интерфейсе его нигде нет. Что Заказчик заказал, то мы и сделали ¯\_(ツ)_/¯
Пример можно посмотреть в Users. Метод MagicSearch создан на основе реальных событий. Хотя надо признать, в оригинале логика еще замудренее была, я то под свой сайт подстраивала.
Но тут фишка в том, что в самой системе в пользовательском интерфейсе есть только обычный поиск, просто строка ввода. Ну, может, парочка фильтров. А вот для интеграции нужна была целая куча доп возможностей, что и было сделано через SOAP-метод.
Функционал супер-поиска доступен только по API, пользователь в интерфейсе его никак не пощупает.
В этом случае у вас обычно есть ТЗ, согласно которому работает API-метод. Ваша задача — проверить его. Типичная задача тестировщика, просто добавьте к стандартным тестам на тест-дизайн особенности тестирования API, и дело в шляпе!
(что именно надо тестировать в API — я расскажу отдельной статьей чуть позднее)
3. Человек вызывает метод
Для примера снова идем в Users. Если мы хотим создать пользователя, надо заполнить уйму полей!
Конечно, это можно сделать в помощью специальных плагинов типа Form Filler. Но что, если вам нужны адекватные тестовые данные под вашу систему? И на русском языке?
Заполнение полей вручную — грустно и уныло! А уж если это надо повторять каждую неделю или день на чистой тестовой базе — вообще кошмар. Это сразу первый приоритет на автоматизацию рутинных действий.
И в данном случае роль автоматизатора выполняет… Postman. Пользователя можно создать через REST-запрос CreateUser. Один раз прописали нормальные “как настоящие” данные, каждый раз пользуемся. Профит!
Вместо ручного заполнения формы (1 минута бездумного заполнения полей значениями «лпрулпк») получаем 1 секунду нажатия на кнопку «Send». При этом значения будут намного адекватнее.
А еще в постмане можно сделать отдельную папку подготовки тестовой базы, напихать туда десяток запросов. И вот уже на любой базе за пару секунд вы получаете столько данных, сколько вручную вбивали бы часами!
Если вы нашли баг и не понимаете, на кого его вешать — разработчика front-end или back-end, уберите все лишнее. Вызовите метод без графического интерфейса. А еще вы можете тестировать логику программы, пока интерфейс не готов или сломан.
4. Автотесты дергают методы
Есть типичная пирамида автоматизации:
Слово API как бы намекает на то, что будет использовано в тестах ツ
GUI-тесты — честный тест, робот делает все, что делал бы пользователь. Открывает браузер, тыкает на кнопочки… Но если что-то упадет, будете долго разбираться, где именно.
API-тесты — все то же самое, только без браузера. Мы просто подаем данные на вход и проверяем данные на выходе. Например, можно внести итоговый ответ в эксельку, и пусть робот выверяет ее, правильно ли заполняются данные? Локализовать проблему становится проще.
Unit-тесты — это когда мы проверяем каждую функцию отдельно. Отдельно смотрим расчет для ячейки 1, отдельно — для ячейки 2, и так далее. Такие тесты шустрее всего гоняются и баги по ним легко локализовать.
Косвенный вызов API
Когда пользователь работает с GUI, на самом деле он тоже работает с API. Просто не знает об этом, ему это просто не нужно.
То есть когда пользователь открывает систему и пытается загрузить отчет, ему не важно, как работает система, какой там magic внутри. У него есть кнопочка «загрузить отчет», на которую он и нажимает. Пользователь работает через GUI (графический пользовательский интерфейс).
Но на самом деле под этим графическим пользовательским интерфейсом находится API. И когда пользователь нажимает на кнопочку, кнопочка вызывает функцию построения отчета.
А функция построения отчета уже может вызывать 10 разных других функций, если ей это необходимо.
И вот уже пользователь видит перед собой готовый отчет. Он вызвал сложное API, даже не подозревая об этом!
Что значит «Тестирование API»
В первую очередь, мы подразумеваем тестирование ЧЕРЕЗ API. «Тестирование API» — общеупотребимый термин, так действительно говорят, но технически термин некорректен. Мы не тестируем API, мы не тестируем GUI (графический интерфейс). Мы тестируем какую-то функциональность через графический или программный интерфейс.
Но это устоявшееся выражение. Можно использовать его и говорить “тестирование API”. И когда мы про это говорим, мы имеем в виду:
Когда мы говорим про тестирование API, чаще всего мы подразумеваем тестирование Remote API. Когда у нас есть две системы, находящихся на разных компьютерах, которые как-то между собой общаются.
И если вы видите в вакансии «тестирование API», скорее всего это подразумевает умение вызвать SOAP или REST сервис и протестировать его. Хотя всегда стоит уточнить!
Резюме
API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».
Что такое API и как он помогает в создании программных систем
Программы, как люди, общаются между собой. Разбираемся, как это происходит с помощью API.
Популярный термин API (англ. Application Programming Interface — программный интерфейс приложения) — это набор способов и правил, по которым различные программы общаются между собой и обмениваются данными.
Все эти коммуникации происходят с помощью функций, классов, методов, структур, а иногда констант одной программы, к которым могут обращаться другие. Это основной принцип работы API.
Пишет о программировании, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Почему API называют интерфейсом
Интерфейс — это граница между двумя функциональными системами, на которой происходит их взаимодействие и обмен информацией. Но при этом процессы внутри каждой из систем скрыты друг от друга.
С помощью интерфейса можно использовать возможности разных систем, не задумываясь о том, как они обрабатывают наши запросы и что у них «под капотом». Например, чтобы позвонить, совсем не обязательно знать, как смартфон обрабатывает нажатия на тачскрин. Важно лишь, что у гаджета есть «кнопка», всегда возвращающая одинаковый результат в ответ на определённые действия.
Точно так же с помощью вызовов API можно выполнить определённые функции программы, не зная, как она работает. Поэтому API и называют интерфейсом.
Как API помогают писать надёжные программы
Программную (и не только) систему, внутреннее устройство которой скрыто или не важно при решении текущей задачи, принято называть « чёрным ящиком» — потому что мы не знаем/не принимаем во внимание то, что там происходит. А само сокрытие деталей реализации — уровнем абстракции.
Уровни абстракции сильно ускоряют процесс разработки, потому что программист может использовать готовые функции API в других приложениях. Это обычная практика. Например, большинство операционных систем предоставляют свои API другим программам, чтобы они получили возможность:
Windows, Linux или OS X сами определяют, какие функции нужно вызвать и какие параметры передать, чтобы были выполнены те или иные действия. Всё это описывается в документации к API, с которым работают разработчики других программ.
Если создатели API выпускают обновление, которое исправляет ошибки, устраняет уязвимости или улучшает производительность, все приложения, использующие это API, автоматически станут работать лучше.
Если какой-то API для облачных вычислений станет быстрее извлекать квадратный корень, то и все использующие его программы тоже начнут работать быстрее: от онлайн-калькуляторов до нейросетей.
Почему API так популярны у программистов
Стороннее API обычно безопаснее, потому что над ним работает коммерческая организация или целое сообщество разработчиков.
Какие функций могут входить в API
Никаких специальных правил или ограничений на набор функций для API нет — разработчики включают в него то, что позволит клиентам использовать нужные возможности приложения.
Например, в API для анализа текстов будут функции поиска всех однокоренных слов, подсчёта количества союзов, выявления часто встречающихся словосочетаний и так далее.
Функции API могут решать не только утилитарные задачи конкретных приложений. Это может стать элементом маркетинга, когда доступ к API предлагается в виде отдельной услуги.
Как компании зарабатывают с помощью API
Компании, разрабатывающие сложные программные системы, часто предоставляют клиентам доступ к API своих продуктов. Например, создатели видеоредактора могут брать дополнительную плату за рендеринг видео на своих серверах. По API они принимают от клиентов все файлы и инструкции, а возвращают готовый ролик.
Так, скажем, Яндекс, помимо прочего, предоставляет платный API своих технологий:
Популярные социальные сети тоже предоставляют доступ к своим API. Через них можно, например, создать игру для ВКонтакте или добавить на сайт авторизацию через Facebook.
При этом компании обычно не раскрывают принципы реализации своих API, поэтому для программистов они остаются «чёрными ящиками».
Как происходит вызов функций API
Способ вызова функции API описывается в документации.
Вот пример вызова методов библиотек в языке Python:
Если API предоставляет функции через интернет (WebAPI), нужно отправить на сервер HTTP-запрос с данными в формате JSON. Пример синтеза речи с помощью API Yandex.SpeechKit:
Этого достаточно, чтобы получить следующее аудио:
Также бывают косвенные вызовы API — когда вызов происходит при участии посредника (другой функции или другого API). Например, когда пользователь нажимает кнопку «Обновить», он тоже взаимодействует с API браузера. Но делает это не напрямую, а через графический интерфейс.
Что в итоге
С развитием технологий использование API, вероятно, станет повсеместным. Даже простейшие встраиваемые системы, вроде «умного утюга», которые состоят из одной программы, сейчас всё активнее подключаются к интернету вещей. Для этого тоже используют API.
Программисту нужно не только уметь создавать свои интерфейсы для взаимодействия программ, но и знать, как использовать чужие. Научиться работать с API вы сможете на наших курсах по программированию — выбирайте любой и становитесь востребованным специалистом.
Проектирование Web API в 7 шагов
Разработка веб API это нечто большее чем просто URL, HTTP статус-коды, заголовки и содержимое запроса. Процесс проектирования – то, как будет выглядеть и восприниматься ваш API – очень важен и является хорошей инвестицией в успех вашего дела. Эта статья кратко описывает методологию для проектирования API с опорой на преимущества веба и протокола HTTP, в частности. Но не стоит думать, что это применимо только для HTTP. Если по какой-то причине вам необходимо реализовать работу ваших сервисов используя WebSockets, XMPP, MQTT и так далее – применяя большую часть всех рекомендаций вы получите практически тот же API, который будет хорошо работать. К тому же полученный API позволит легче разработать и поддерживать работу поверх нескольких протоколов.
Хороший дизайн затрагивает URL, статус-коды, заголовки и содержимое запроса
Обычно руководства по проектированию Web API фокусируются на общих концепциях: как проектировать URL, как правильно использовать HTTP статус-коды, методы, что передавать в заголовках и как спроектировать дизайн содержимого, которое представлено сериализованными данными или графом объектов. Это всё очень важные детали реализации, но не настолько в смысле общего проектирования API. Проектирование API – это то, как сама суть сервиса будет описана и представлена, то что вносит значительный вклад в успех и удобность использования Web API.
Хороший процесс проектирования или методология предоставляют набор согласованных и воспроизводимых шагов для создания компонентов сервисов, которые будут доступны в виде Web API. Это значит, что такая прозрачная методология может быть использована разработчиками, дизайнерами и архитекторами для координации своих действий по реализации ПО. Использованная методология так же может уточнятся со временем по мере того, как улучшается и автоматизируется процесс без ущерба для деталей методологии. На самом деле, детали реализации могут меняться (например, платформа, ОС, фреймворки и стиль UI) независимо от процесса проектировки, когда эти две активности полностью разделены и задокументированы.
Проектирование API в 7 шагов.
Далее следует краткий обзор методологии описанной в книге «RESTful Web APIs» за авторством Ричардсона и Амундсена (Richardson and Amundsen). Статья не предполагает детального разбора каждого шага, но постарается дать общее понимание что делается на каждом шаге. Также, читатели могут использовать этот обзор как руководство для разработки процесса проектирования Web API, который учитывает специфику ваших знаний и целей бизнеса.
Заметки на полях: Да, руководство в семь шагов может выглядеть достаточно большим, но реально тут только 5 шагов по проектированию и 2 как дополнения, касающиеся реализации и публикации сервисов. Эти два дополнения построены вокруг процессов и описывают весь процесс от начала до конца.
В своём плане вы должны учесть возможную итеративную природу процесса создания сервиса. Например, вы можете проходить через Шаг 2 (Создание диаграмм состояний) и понять, что надо еще кое-чего сделать в Шаге 1 (Перечислить все компоненты). Когда вы будете писать код (Шаг 6), вы можете обнаружить, что пропустили пару моментов в Шаге 5 (Создание семантического профиля), и так далее. Ключевой момент заключается в использовании руководства для обнаружения как можно большего количества деталей и желании возвращаться на шаг-два назад, чтобы описать пропущенные моменты. Итеративность – ключ к построению наиболее полного представления вашего сервиса и видению как он может быть использован клиентскими приложениями.
Шаг 1: Перечислить все компоненты
Первым шагом предлагается перечислить все типы данных, которые клиентское приложение может захотеть получить или передать с помощью сервиса. Мы зовём это семантическим описанием. Семантическое – потому что отображает значение данных в приложении, и описание – потому что содержит описание того, что происходит в самом приложении. Заметьте, что вы должны работать с точки зрения клиентского приложения, а не сервиса. Важно разработать удобный API для использования клиентом.
Шаг 2: Нарисовать диаграмму состояний
Следующим шагом будет нарисовать диаграмму состояний для предполагаемого API. Каждый блок на диаграмме представляет возможное состояние – документ который включает одно или более семантических дескрипторов, найденных на первом шаге. Вы можете использовать стрелки для обозначения переходов от одного блока к другому, от одного состояния к следующему. Эти переходы инициируются запросами.
Пока не стоит беспокоится на счёт определения какой метод используется для каждого перехода. Просто укажите является ли переход безопасным (HTTP GET), небезопасный/не идемпотентный (HTTP POST) или небезопасный/идемпотентный (PUT)
Заметки на полях: Идемпотентные действия – такие, которые можно повторять без неожиданных сайд-эффектов. Например, HTTP PUT является идемпотентным потому что спецификация говорит, что сервер должен использовать значения состояния, полученные от клиента, для замены любых значений в целевом ресурсе. В то время как HTTP POST не идемпотентен, так как спецификация HTTP указывается что значения, переданные с помощью POST должны быть добавлены к существующим ресурсам, а не замещены.
В нашем случае, клиентское приложение для простейшего «Списка дел» может потребовать доступ к пунктам списка, возможность фильтрации, просматривать отдельные пункты и отмечать их как завершённые. Многие из этих действий используют значения состояний для передачи данных между клиентом и сервером. Например, действие «добавить элемент» позволяет клиенту передавать значения состояний title и dueDate. Ниже диаграмма, которая иллюстрирует основные действия:
Как только вы пройдёте пару раз через эти два шага у вас будет хорошее понимание всех данных и действий в которых нуждается клиент для взаимодействия с вашим сервисом.
Шаг 3: Согласование магических строк
Заметки на полях: Использование общих имён для дескрипторов может быть хорошей идеей для внешнего интерфейса, однако вас никто не заставляет использовать их для ваших внутренних нужд. Имеются ввиду, например, имена для баз данных. Сервис самостоятельно может использовать карту соответствий между внешними и внутренними именами без каких-либо проблем.
Для To-Do сервиса из примера, у меня получилось найти приемлемые существующие имена для всех дескрипторов кроме одного – «create-item». В этом случае, я обратился к созданию уникального URI на основе правил из Web-Linking RFC 5988. Во время выбора конвенционных имён для интерфейса вас всегда будут преследовать компромиссы. Редко когда удаётся найти идеальное попадание к внутренним именам и это нормально.
Шаг 4: Выбор типа гипермедиа
Следующим шагом в процессе проектирования вашего API будет выбор типа данных, который будет использоваться для передачи сообщений между сервером и клиентом. Одним из отличительных знаков сети является то, что данные передаются стандартизированными документами через общий интерфейс. Очень важно выбрать такой тип, который поддерживает одинаково дескрипторы данных («identifier», «status») и действий («search», «edit»). Таких форматов достаточно мало.
Разработка web API
Интро
Это краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя из компании Apigee Labs. Apigee занимается разработкой различных API-сервисов и консталтингом. Кстати, среди клиентов этой компании засветились такие гиганты, как Best Buy, Cisco, Dell и Ebay.
В тексте попадаются комментарии переводчика, они выделены курсивом.
Собираем API-интерфейсы, которые понравятся другим разработчикам
Понятные URL для вызовов API
Первый принцип хорошего REST-дизайна — делать вещи понятно и просто. Начинать стоит с основных URL адресов для ваших вызовов API.
Ваши адреса вызовов должны быть понятными даже без документации. Для этого возьмите себе за правило описывать любую сущность с помощью коротких и ясных базовых URL адресов, содержащих максимум 2 параметра. Вот отличный пример:
/dogs для работы со списком собак
/dogs/12345 для работы с отдельной собакой
Существительные — это хорошо, а глаголы — плохо
Видите эти вызовы? Это ужас.
Вместо глаголов — HTTP
POST /dogs — создать новую собаку
GET /dogs — получить список собак
PUT /dogs — редактирование всех собак сразу
DELETE /dogs — удаление всех собак
POST /dogs/12345 — вернуть ошибку (собака 12345 уже создана)
GET /dogs/12345 — показать информацию о собаке
PUT /dogs/12345 — редактировать собаку 12345
DELETE /dogs/12345 — удалить
Базовые URL выглядят просто, глаголы не используются, все интуитивно и понятно. Красота!
Множественное число
/checkins у Foursquare
/deals y GroupOn
/Product y Zappos
Конкретные имена лучше абстрактных
Абстрактные названия — это часто считается крутым у архитекторов API. И это совсем не круто для тех, кто потом с этим API будет работать.
/blogs, /videos, /news, /articles — это выглядит очевидным. А вот /items и /assets — нет.
Связи
Мы только что представили связь двух ресурсов в простом виде. Метод GET в этом случае вернет нам список собак владельца 5678, а метод POST — добавит владельцу 5678 еще одну собаку.
Связи очень удобно представлять в виде /ресурс/идентификатор/ресурс.
Сложные вещи нужно прятать за знаком «?»
А что насчет ошибок?
SimpleGeo дают сообщение об ошибке в коде HTTP и снабжают его небольшим пояснением в теле ответа.
Используйте коды ответов HTTP
Google GData
200 201 304 400 401 403 404 409 410 500
Netflix
200 201 304 400 401 403 404 412 500
Digg
200 400 401 403 404 410 500 503
Какие коды ошибок HTTP стоит использовать?
И, конечно же, при ошибке всегда нужно прикладывать сообщение для разработчиков. А приложить к сообщению ссылку на документацию по проблеме — это еще лучше.
Никогда не выпускайте API без указания версии
Twilio требует при каждом запросе к API передавать время, когда приложение разработчика было скомпилировано. На основе этой даты Twilio определяет, какую версию API нужно предоставить приложению. Это умный и интересный подход, но слишком сложный. А еще можно легко запутаться с датами.
Salesforce.com вставляет v20.0 в середину адреса API запроса. И это очень хороший подход. Но не стоит использовать точку в нумерации версии — это провоцирует излишне частые изменения в интерфейсе API. Можно сколь угодно часто менять логику работы внутри API, но вот сами интерфейсы должны меняться максимально редко. Так что лучше обойтись без точки и не искушать себя.
Facebook тоже использует нумерацию версий в запросе, но прячет её в параметры запроса. И этот подход плох тем, что после очередного внедрения новой версии API все приложения, не передающие версию в запросе, начинают глючить.
Как реализовать версии в API?
Используйте префикс v, целые числа и располагайте номер версии в левой части адреса. Например, /v1/dogs.
Держите в рабочем виде как минимум одну предыдущую версию
Еще можно указывать версию в заголовках ответа сервера. Это может давать некоторые дополнительные возможности при работе с API. Но если вы используете множество разных версий и требуете обязательно указывать их в заголовках — это симптом большой проблемы.
Частичный ответ
Перечислять необходимые поля через запятую в адресе запроса — это очень простой и удобный подход. Берите его на вооружение.
Сделайте простую паджинацию
Facebook: смещение 50 и лимит 25
Twitter: страница 3 и 25 записей на страницу
Linkedin: с 50-й записи прочитать 25
Еще стоит приложить к каждому ответу мета-информацию: текущая страница, сколько всего записей доступно.
Предусмотрите значения по умолчанию: если пользователь не передал в запросе параметры паджинации, считайте лимит равным 10 и смещение — равным 0 (вывести первые 10 записей).
А что насчет действий?
Не все API-ресуры являются записями, которые можно читать, редактировать и удалять. Бывают и API-действия. Переводы, вычисления, конвертации — все это действия.
Лучше всего для таких запросов использовать глаголы, а не существительные.
Убедитесь, что даже просто глядя на список вызовов в документации можно отличить сущности от действий.
Поддержка нескольких форматов
Кстати, Digg позволяет установить формат ответа и через HTTP-заголовок Accept.
Мы рекомендуем подход Foursquare.
Еще можно предусмотреть ответы API не только в разных форматах, но и ответы для разных типов клиентов. Например, можно сделать API, способное работать одновременно с iOS-приложением и фронт-эндом веб-приложения. Это может выглядеть так: /dogs.ios и /dogs.web.
Формат по умолчанию
JSON — пожалуй, лучший формат по умолчанию. Он менее многословен, чем XML. Его поддерживают все популярные языки. Его можно сразу же использовать на фронт-энде веб-приложения.
Названия атрибутов
Twitter created_at
Bing DateTime
Foursquare createdAt
Существует много конвенций именования переменных. Нам, как спецам по Ruby on Rails, конвенция Twitter близка по духу. Но лучшим подходом мы считаем подход Foursquare: — camelCase (переменные с маленькой буквы, классы — с большой). Такой способ именования наиболее симпатичен для подачи данных в JSON: данные выглядят похоже на JavaScript. Что, в общем, логично для JSON.
Хоть автор и советует почаще использовать camelCase, лучше все же подумать о клиенте и потом уже принимать решение. Например, с вашим API может общаться программа, написанная на C, а ей лучше использовать несколько_другую_конвенцию.
Поиск
Соберите все API вызовы на одном домене
api.facebook.com этот адрес появился первым
graph.facebook.com этот адрес ввели после внедрения глобального графа
stream.twitter.com
api.twitter.com
search.twitter.com
Легко догадаться, как Facebook и Twitter завели себе по несколько адресов: проще направлять запросы в разные кластеры через DNS, чем через логику. Но мы делаем приятный API для разработчиков, поэтому опять выберем подход Foursquare.
На всякий случай напомню, что разработчикам небольшого бэкенда для веб-приложения не надо выделять отдельный домен, чтобы не создавать проблемы с кроссдоменными ajax-запросами на фронт-энде.
Делайте редиректы
Коды HTTP ответов и исключения на клиенте
В результате ошибки будут приходить с кодом 200.
Предусмотрите в своем API параметр suppress_response_codes и сделайте его равным true по умолчанию.
А что если клиент поддерживает ограниченный набор HTTP методов?
чтение /dogs
создание /dogs?method=post
редактирование /dogs/1234?method=put
удаление /dogs/1234?method=delete
Будьте аккуратны с таким подходом! Если вы будете неаккуратно обращаться с такими ссылками и не обеспечите им должной безопасности, боты (вроде поискового робота Google) могут вызывать такие ссылки. И вы получите бесконечно создающиеся и удаляющиеся записи при каждом заходе бота.
Авторизация
PayPal Permissions Service API
Facebook OAuth 2.0
Twitter 1.0a
Обратите внимание на то, что PayPal реализовали свою систему авторизации еще до того, как был изобретен OAuth.
Если вам требуется авторизация пользователей через сторонние приложения — только OAuth. И ни в коем случае не делайте что-то вроде OAuth, но «немного другое».
«Болтливые» API
«Болтливые» — это значит, что для выполнения популярных операций приходится выполнять 3-4 вызова API подряд. Это плохо.
Попробуйте посмотреть на ваши вызовы глазами пользователя. Вы увидите, что примерно 80% вызовов принимают и отдают данные одинаковой структуры. Это значит, что вполне можно сделать псевдонимы для последовательностей вызовов. После этого пользователь сможет единожды направить данные на вход, и вся цепочка вызовов выполнится сама.