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

Собираюсь делать некий веб-сервис с открытым API (yii rest). Что можно почитать по поводу спецификаций на описание API? Какие-либо best practice, ГОСТы, спецификации (ну кроме - "делайте свой API так, чтобы было понятно"). Примеры хорошо документированных API.
Вчера на Хабре была статья Типичные ошибки API платежных систем, где мне уже дали ссылку (за что огромное спасибо) на RestApiTutorial .
Вот что-то подобное.
  • Вопрос задан
  • 6626 просмотров
Решения вопроса 1
Fesor
@Fesor
Full-stack developer (Symfony, Angular)
Очень хорошая документация у LinedIn. Это как пример оформления документации скорее.

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

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

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы