Где проектировать Restful API?

Question

[BulatDos]

Всем привет, до настоящего времени описывал API на Restful в ручную, скажите - существует ли какой нибудь "моделлер" для этого дела, например как для бд?

Answer 1

[Станислав Макаров]

RAML (самый молодой, но рекомендую)
Swagger
Apiary

Это фреймоворки для проектировния API. По сути предоставляют свой DSL для описания и ДОКУМЕНТИРОВАНИЯ (!) API. К большинству из них идут инструменты по генерации читабельных доков и всякие mock-инструменты и генераторы клиентов-загрушек и сервисов-заглушек (для тестирования сервисов и клиентов соответственно). Вот например тулзы для Сваггера: swagger.io/swagger-codegen :

The Swagger codegen project allows generation of both client libraries and server stubs from a Swagger definition.

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

P.S. Есть еще различные модели гипермедийных API (JSON-LD, HAL, Siren, и т.д.), но это пока не очень популярные вещи, поэтому если не готовы быть одним из первопроходцев, лучше попробуйте их потом, когда наберут популярность (если наберут).

Comments

[BulatDos]

Спасибо!

[Станислав Макаров]

pygame
> Под него есть генераторы кода?
Пользовался генератором под ASP.Net WebAPI, вполне выполняет свою функцию: в студию ставится Extension, в webapi проект добавляется raml-файл, по нему генерится код контроллеров на шарпе, содержащий методы и атрибуты с маршрутами из вашего API. Эти методы-заглушки вызывают парные им методы, где вы уже пишете конкретную реализацию.

Почему это удобно? Потому что RAML-файл становится основным документом-договором по API. Т.к. из него генерится код, то при изменении его описания при сборке webapi-проекта сразу же всплывают все проблемы, связанные с изменением "договора", например нереализованные экшены контроллера, или изменившийся список параметров. Лично я очень люблю, когда инструмент мне гарантированно скажет хотя бы о некоторых проблемах (поэтому и пользуюсь в основном компилируемыми языками). При этом, тут же в RAML файле вы пишете описание экшенов и передаваемых в обе стороны параметров и данных, можно даже JSON-схему для запросов и ответов указывать. То есть по тому же самому RAML-файлу вы можете сгенерить и доки для чтения человеком.

Поэтому вывод очень простой: эти инструменты хороши, потому что а) они решают важнейшую проблему всей информатики - синхронизацию информации об одном и том же объекте в нескольких местах. Вместо рукописных доков и кода, за соответствием которых надо следить, у вас остается ОДИН авторитетный источник и для человеческой документации, и для "компиляторской" документации в виде кода для клиента и сервера. б) они решают проблему стандартизации. Очевидно, что для текстового человеческого описания без всякого синтаксиса невозможно сгенерить,например, тестовый сервис-заглушку, или клиент-заглушку. в) добавляя стандартизацию, они добавляют семантику, в том числе и в документацию. Для тех же целей создаются и другие форматы, например DocBook. Только в докбуке вы оперируете понятиями "параграф", "глава" и "фрагмент кода", а тут сущности еще более высокоуровневые: "описание экшена", "описание ресурса" и т.д.

Разумеется, возникает стандартная дилемма: усложнить процесс разработки и пользоваться подобными тулзами, или не усложнять, и писать все на Markdown и не заморачиваться. Это каждый решает сам в каждом отдельном проекте.

Answer 2

[FoxInSox]

https://apiary.io

Answer 3

[Никита Конин]

swagger.io

Answer 4

[⚡ Kotobotov ⚡]

на текущий момент все сами придумывают свой "язык апи" для описания своих сервисов, тк нет определённости какой именно функционал и как вы хотите показать через апи.