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

Question

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

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

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

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

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

Answer 1

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

1. забудьте все технологические проблемы, кроме HTTP и типы мультимедиа .

2. Определите основные случаи использования, когда клиент будет взаимодействовать с API.

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

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

4. Как форматируются и идентифицируются эти ссылки, очень важно. Самое важное решение, которое вы примете при определении REST API, - это выбор типов носителей .Вам также нужно найти стандартные способы представления этой информации о связях (например, Атом , микроформаты , отношения связей атомов , Html5 отношений связей ) или если у вас есть особые потребности, и вам не нужно действительно широкий охват для многих клиентов, то вы можете создать свои собственные media-types .

5. Документируйте, какэти типы носителей структурированы и какие ссылки / отношения ссылок они могут содержать.Конкретная информация о типах носителей имеет решающее значение для клиента.Возвращение сервером Content-Type: application / xml бесполезен для клиента, если он хочет сделать что-то большее, чем анализ ответа.Клиент не может знать, что содержится в ответе типа application / xml.Некоторые люди считают, что вы можете использовать XML-схему, чтобы определить это, но у этого есть несколько недостатков, и это нарушает ограничение REST «самоописательное сообщение».

6. Помните, что выглядит URLLike не имеет абсолютно никакого отношения к тому, как должен действовать клиент.Единственное исключение из этого состоит в том, что тип мультимедиа может определять использование шаблонных URI и может определять параметры этих шаблонов. Структура URL станет существенной, когда речь заходит о выборе серверной инфраструктуры .Сервер контролирует структуру URL, клиент не должен заботиться.Однако не позволяйте серверной инфраструктуре диктовать, как клиент взаимодействует с API, и будьте очень осторожны при выборе инфраструктуры, требующей изменения вашего API. HTTP должен быть единственным ограничением, касающимся взаимодействия клиент / сервер .