Создание пользовательского API - требуется проверка логики

Question

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

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

Мои вопросы:

Это то, что вы ожидаете увидеть как взаимодействие API?

Я что-то упустил?

Объяснение API:

Я собираюсь использовать протокол HTTP Type 1 для связи и уникальный ключ API для аутентификации.

Я ожидаю, что это будет происходить через запросы CURL через соединение SSL.

Пример успешного (200 ОК) XML-ответа (запрос ограничения скорости):

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <short_message>Request Complete</short_message>
    <long_message>Rate Limit Status Response</long_message>
    <response_data>
        <rate_limit>40</rate_limit>
        <rate_used>31</rate_used>
    </response_data>
</node>

Пример ошибочного ответа XML (будет отправлен с соответствующим заголовком 400/500);

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <error_code>1201</error_code>
    <short_message>API Error</short_message>
    <long_message>The requested API version (1.5) is invalid</long_message> 
</node>

Кроме того, я устанавливаю коды ошибок, которые будут использоваться в поисковой документации для облегчения мигрени у других разработчиков. Пропуск / неудача запроса будет передан через соответствующие HTTP-коды - Успешно (200), неверные запросы (400), метод не найден (404), ошибка аутентификации (403) и т. Д.

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

Наконец, разработчики смогут запрашивать все ответы в сериализованных массивах XML, JSON или PHP.

Внутренние части моего кода очень просты. Все данные передаются через POST (возможно, с использованием CURL или другой альтернативы), включая уникальный ключ API Этот ключ API связан с пользователем в системе, что позволит внутренним методам выполнять ограниченный набор функций, которые включены для этого конкретного пользователя.

Я придерживаюсь «золотого правила» API - «Всегда добавлять, никогда не удалять».

Итак ... что еще мне следует рассмотреть и что я пропустил?

Answer 1

Шейн,

Я предполагаю, что ваша цель - создать RESTful API - это правда?

Мой ответ применим, только если это предположение верно - я не пытаюсь критиковать ваш дизайн, просто его RESTfulness.

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

Я постараюсь, чтобы вы начали с краткого ответа ниже, но, пожалуйста, посмотрите на http://nordsc.com/ext/classification_of_http_based_apis.html, где я обсуждаю эту проблему немного больше. Тогда вы, вероятно, можете разбить все это на более мелкие вопросы и вернуться сюда или посетить остальные обсуждения в группах Yahoo: http://tech.groups.yahoo.com/group/rest-discuss/

Теперь краткие комментарии к вашему дизайну:

1. Вы не должны использовать свои собственные коды ответов, а должны использовать только те, которые предоставляются HTTP. Вы можете создать свои собственные, но они должны быть в целом применимы и не привязаны к вашему приложению или взаимодействию.

2. Вы должны использовать определенный тип носителя, а не только application / xml. Если ни один из существующих типов не соответствует вашим потребностям (или может быть расширен для этого), вы можете разработать свой собственный. На самом деле основное дизайнерское занятие должно быть потрачено на тип носителя. Здесь находится ваша семантика домена.

3. Вы должны придерживаться ограничения гипермедиа, чтобы быть действительно ОТДЫХАЮЩИМ. Это означает, что клиент должен быть снабжен ссылками и / или формами, чтобы узнать, что он может делать дальше.

Используя приведенную выше классификацию, ваш API выглядит как Тип I на основе HTTP * (http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one), при условии, что вы не помещаете действия в свои URI, что делает его RPC URI-туннелирование (http://nordsc.com/ext/classification_of_http_based_apis.html#uri-rpc)

Надеюсь, это поможет вам в достижении вашей общей цели.

Jan

Answer 2

Несколько вещей:

1) Размещение заголовков ответов в разных местах - заголовок HTTP И код ответа - определенно вызовет путаницу. Некоторые разработчики проверят это в одном месте, некоторые в другом. Если вы хотите пойти по этому пути, обязательно убедитесь, что коды ответов идентичны между заголовками HTTP и возвращенным XML.

2) Вашему серверу НЕ нужно возвращать версию API с каждым ответом. Ты тратишь биты на провод. Если клиенту нужна конкретная версия API, попросите его отправить ее в запросе. Вам не нужно отправлять его обратно им.

3) Объединить код ответа и request_status. Посмотрите, как HTTP это делает: 200-299 означает успех. 400-499 означает, что клиент тупой. 500-599 означает, что сервер облажался.

Answer 3

Если вы действительно строите REST-сервисы, учтите следующее:

• request_status, следует отбросить в пользу html-кода ответа (как минимум 200: ОК, 400: Неверный запрос, 401: Несанкционированный, 403: Запрещен и 500: Внутренняя ошибка), response_code может потребоваться для поиска в вашей документации объяснение проблемы.
• Вы хотите указать другой формат, формат ответа должен зависеть не от URL, а от заголовка Accept

Answer 4

О вашей идее «единого URL / конечной точки» - имейте в виду, что с Apache вы можете обслуживать потенциально неограниченное количество URL-адресов из одного скрипта с помощью правил перезаписи URL-адресов. Это означает, что с правильно определенным файлом .htaccess в каталоге вашего скрипта «конечная точка» вы можете иметь свой веб-сервер автоматически «отображать» входящие запросы, например, так:

/foo/slice/1234 => /foo/?action=slice&oid=1234
/foo/dice/3456  => /foo/?action=dice&oid=3456
/foo/chop/4567  => /foo/?action=chop&oid=4567

Это может быть очень полезно, если вы решите, что все-таки хотите обслуживать URL-адреса "RESTful" (и могут быть настроены для работы с режимами HTTP-запроса GET, POST, PUT, DELETE, HEAD).

Answer 5

Рассматривали ли вы использование версионных конечных точек? Они могут потребовать немного больше планирования и обслуживания с вашей стороны, но вашим пользователям не придется переписывать свой код каждый раз, когда вы решите изменить параметры / возвращаемые значения.

Если вы придумали план устареть, а затем удалить старые версии, это не должно быть слишком болезненным.

Answer 6

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

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

Answer 7

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