Как правильно описывать API?

Question

[Сергей]

Собираюсь делать некий веб-сервис с открытым API (yii rest). Что можно почитать по поводу спецификаций на описание API? Какие-либо best practice, ГОСТы, спецификации (ну кроме - "делайте свой API так, чтобы было понятно"). Примеры хорошо документированных API.
Вчера на Хабре была статья Типичные ошибки API платежных систем, где мне уже дали ссылку (за что огромное спасибо) на RestApiTutorial .
Вот что-то подобное.

Answer 1

[Сергей Протько]

Очень хорошая документация у LinedIn. Это как пример оформления документации скорее.

Так же почитайте что такое ресурс. что такое uri.... Большая часть правил по которым нужно формировать API строятся как раз на этих принципах.

Если говорить о best practice, есть еще HATEOAS и Json Api. чем это все хорошо - позволяет автоматически генерировать клиентский код. Скажем помниться мне для angular.js есть модуль позволяющий легко и просто взаимодействовать с HATEOAS. Но если честно, я редко сталкивался с апишками где это используется. Сходу вспомню что Sun (oracle) использует в енто дело в своих апишках для работы с клаудами.

Comments

[Сергей]

Да, спасибо большое. Есть что поизучать