Как мне создать хороший (веб) API

Question

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

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

У кого-нибудь есть идеи или примеры сайтов с особенно хорошими API, которые вы использовали?

Answer 1

Прочитайте книгу RESTful Web Services , которая дает вам хороший обзор о том, как использовать REST на практике, и достаточно быстро набрать скорость, чтобы начать работу с некоторой уверенностью. Это более полезно, чем просто смотреть на существующий API, поскольку в нем также обсуждаются варианты проектирования и компромиссы.

Answer 2

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

2) Сохраняйте правила переписывания ваших URL-адресов (если таковые имеются) как можно более простыми / понятными (но не более простыми), при этом делая ваши URL-адреса максимально красивыми (но не более).

3) Всегда ищите лучший код состояния HTTP, который вы можете найти для каждого ответа (и не забудьте, например, о 202 и 207).

4) Реализовать логику проверки фашистских параметров и информационные сообщения об ошибках.

5) Используйте заголовки HTTP-запросов, где это уместно, вместо параметров (например, Accept, чтобы позволить клиентам указывать желаемый формат данных ответа).

6) Организуйте свои " существительные " таким образом, что URL-адреса, используемые различными клиентскими аудиториями, разделяются рядом с «корнем»; вашего URL-дерева (это облегчает применение различных механизмов аутентификации для этих разных аудиторий, если это необходимо, или даже отображает различные части вашего URL-дерева на разные серверы).

7) Если вы обслуживаете обычные веб-страницы из того же домена, что и ваши API, и используете те же учетные данные для аутентификации, для заголовков X-Requested-With в запросах API требуется заголовок, чтобы избежать уязвимостей XSRF.

Answer 3

Я бы взглянул на проверенные API:

<Ол>

API YouTube

API Twitter

Существует много споров о том, являются ли эти API "хорошими" но я думаю, что их успех продемонстрирован, и все они просты в использовании.

Answer 4

Используйте REST .

Архитектура веб-сервисов RESTful проста в реализации и использует сильные стороны и семантику HTTP для своих целей. Он ориентирован на ресурсы, как и сама сеть.

Веб-сервисы Amazon , Google и многие другие предлагают API-интерфейсы REST для взаимодействия со своими продуктами.

Answer 5

Используйте REST.

Ознакомьтесь со стандартами для API или скопируйте идеи одного из популярных.

Будьте осторожны при аутентификации пользователей.

Начать очень просто.

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