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

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

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

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

Ответ 1

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

Ответ 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.

Ответ 3

Я бы посмотрел проверенные API:

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

Ответ 4

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

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

Amazon Web Services, Google и многие другие предлагают API REST для взаимодействия со своими продуктами.

Ответ 5

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

Прочитайте стандарты API-интерфейсов или скопируйте идеи из одного из популярных.

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

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

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