Что должен знать разработчик перед созданием API для веб-сайта на базе сообщества?

Что нужно разработчику, разрабатывающему и внедряющему API для сайта на базе сообщества, знать перед началом тяжелого кодирования? Там есть куча API-интерфейсов, например Twitter API, Facebook API, Flickr API и т.д., которые являются хорошими примерами. Но как бы вы создать свой собственный API?

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

С другой стороны, мышление с точки зрения пользователя (я имею в виду разработчика, который собирается использовать ваш API), что бы вы искали в API? Хорошая документация? Много примеров кода?

Этот вопрос был вдохновлен вопросом Джоэла Коэхорна "Что должен знать разработчик до создания общедоступного веб-сайта?" .

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

Ответ 1

Если вы действительно хотите определить REST api, выполните следующие действия:

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

При создании REST api легче воспринимать его как "пользовательский интерфейс" для машины, а не подвергать объектной модели или модели процесса. Представьте себе, что машина автоматически переводит api, получая ответ, следуя ссылке, обрабатывая ответ и следуя следующей ссылке. Клиент никогда не должен создавать URL-адрес, основываясь на своих знаниях о том, как сервер организует ресурсы.
Как эти отформатированные и идентифицированные ссылки являются критическими. Самое важное решение, которое вы сделаете при определении REST API, - это ваш выбор типов носителей. Вам либо нужно найти стандартные способы представления этой информации о ссылках (подумайте Atom, microformats, атомные связи-отношения, Html5 отношения связей), или если у вас есть специализированные потребности, и вам не нужен действительно широкий охват для многих клиентов, тогда вы можете создать свой собственный media-types.
Документируйте, как структурируются эти типы носителей и какие ссылки/отношения ссылок они могут содержать. Конкретная информация о типах носителей имеет решающее значение для клиента. Возвращение сервера Content-Type: application/xml бесполезно для клиента, если он хочет сделать что-то большее, чем разобрать ответ. Клиент не может знать, что содержится в ответе типа application/xml. Некоторые люди считают, что вы можете использовать XML-схему для определения этого, но есть несколько недостатков этого, и это нарушает ограничение REST "самоописательное сообщение".
Помните, что то, как выглядит URL-адрес, абсолютно не влияет на то, как должен работать клиент. Единственным исключением из этого является то, что тип носителя может указывать использование шаблонных URI и может определять параметры этих шаблонов. Структура URL-адреса станет значимой, когда дело доходит до выбора рамки на стороне сервера. Сервер управляет структурой URL, клиенту все равно. Однако не допускайте, чтобы структура на стороне сервера определяла, как клиент взаимодействует с API, и будьте очень осторожны в выборе структуры, требующей изменения вашего API. HTTP должен быть единственным ограничением взаимодействия с клиентом и сервером.