Что разработчик должен знать прежде, чем создать API для основанного на сообществе веб-сайта?
Какие вещи должны, разработчик, разрабатывающий и реализующий API для основанного на сообществе веб-сайта, знает прежде, чем запустить тяжелое кодирование? Существует набор API там как Программный интерфейс Твиттера, Facebook API, Flickr API, и т.д. которые являются всеми хорошими примерами. Но как Вы создали бы свой собственный API?
Какие технологии Вы использовали бы? Я думаю, что это - хорошая идея использовать подобный REST интерфейс так, чтобы API был доступен от различных инструментов платформ/клиентов/браузеров/командной строки (как завихрение).Я прав? Я знаю, что все принципы веб-разработки должны быть встречены как кэширование, доступность, масштабируемость, безопасность, защита от потенциальных DoS-атак, проверки, и т.д. И когда дело доходит до API некоторыми самыми важными вещами является обратная совместимость и документация. Я пропускаю что-то?
С другой стороны, думая с точки зрения пользователя (я имею в виду разработчика, который собирается использовать Ваш API), что Вы искали бы в API? Хорошая документация? Много примеров кода?
Этот вопрос был вдохновлен вопросом Joel Coehoorn, "Что разработчик должен знать прежде, чем создать общедоступный сайт?".
Этим вопросом является общественная Wiki, таким образом, я надеюсь, что Вы поможете мне положить на одно место все вещи, которые должны быть обращены при создании API для основанного на сообществе веб-сайта.
1 ответ
Если вы действительно хотите определить API для отдыха, то сделайте следующее:
Забудьте все вопросы технологии, отличные от типов HTTP и Media .
Определите основные случаи использования, когда клиент будет взаимодействовать с API
, запись клиента, который выполняет те «случаи использования» против гипотетического HTTP-сервера. Информация только информация о том, с которой клиент должен начинаться, - это ответ от запроса Get в URL корневого API . Клиент должен определить тип мультимедиа ответа от заголовка типа содержимого HTTP, и оно должно рассматривать ответ. Этот ответ должен содержать связи с другими ресурсами, которые позволяют клиенту выполнять все необходимые операции API.
При создании API для отдыха легче подумать об этом как «пользовательский интерфейс» для машины, а не выдержки объектной модели или модели процесса. Представьте себе машину, навигацию на API программно, получая ответ, следуя ссылке, обработав ответ и следующую следующую ссылку. Клиент никогда не должен построить URL на основе его знаний о том, как сервер организует ресурсы .
Как эти ссылки отформатированы и идентифицированы, имеют решающее значение. Самое важное решение , которое вы сделаете в определении API для отдыха, является вашим выбором типов носителей . Вам либо нужно найти стандартные способы представлять эту ссылку информацию (подумайте Atom , Microformats , Atom Link-соотношения , Строки HTML5 ) Или если у вас есть специализированные потребности, и вам не нужно очень широко охватить многих клиентах, то вы можете создать свои собственные типов медиа .
Документ о том, как эти типы средств массовой информации структурированы и какие ссылки / ссылки могут содержать их. Конкретная информация о типах СМИ имеет решающее значение для клиента. Наличие возвращаемого сервера типа Content: Application / XML бесполезно для клиента, если он хочет сделать все больше, чем проанализируют ответ. Клиент не может знать, что содержится в ответе приложения типа / XML. Некоторые люди считают, что вы можете использовать XML-схему для определения этого, но есть несколько недостатков, и он нарушает остальное «самоописательное сообщение».
Помните, что выглядит URL, как выглядит абсолютно не имеет никакого отношения к тому, как клиент должен работать. Единственное исключение из этого, состоит в том, что тип медиа может указывать использование шаблонных URI и может определить параметры этих шаблонов. Структура URL станет значительной, когда речь идет о выборе Server Side Framework . Сервер контролирует структуру URL, клиент не должен заботиться. Тем не менее, не позволяйте серверу боковой рамки дикторировать, как клиент взаимодействует с API, и будьте очень осторожны в том, чтобы выбрать рамки, которые требуют, чтобы вы изменили свой API. HTTP должен быть единственным ограничением относительно взаимодействия клиента / сервера .