3 лучших инструмента для описания RESTful API

Взаимодействие различных сервисов с использованием АPI, из новаторства превращается в обыденность. Количество бесплатных и платных API уже исчисляется тысячами, и с каждым днем их число активно растет. А почему бы и нет? Продажа удаленных запросов к своему новаторскому сервису может принести больше прибыли, чем распространение услуг через свою площадку. И пусть, в таком случае, уже ваши клиенты ломают голову и тратят деньги на привлечение аудитории. Используя свой опыт работы, я предлагаю краткий обзор лучших решений по реализации API на сегодняшний день.

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

Тем не менее, уже появились явные лидеры гонки, о которых далее пойдет речь более подробно.

www.mashape.com ^[1]
Этот проект отличается от многих других. Его главная задача — не описание, а продажа API через каталог готовых решений. Сервис создает поддомен для каждого клиента и скрывает реальные пути к API за проксированием. Mashape размещает API в своем каталоге. У каждого пользователя есть возможность воспользоваться конструктором тарифов и начать зарабатываться на каждом запросе. Благодаря проксированию запросов, Mashape может вести учет и лимитировать доступ к API.
Фактического языка разметки у Mashape нет, все настраивается в окне браузера. Доступна удобная функция тестрирования созданного API.
Проект разработал базовый SDK для запросов и ответов и опубликовал как отдельный проект www.unirest.io ^[2].
Приведу пример API популярного сайта Pinterest: www.mashape.com/ismaelc/pinterest-1 ^[3]
Удобный генератор позволяет сразу получить код упрощенного запроса к API для языков программирования: PHP, Java, Node.js, Python, Objective-C, Ruby, .NET.

www.swagger.io ^[4]
Swagger уже разрабатывают достаточно давно. Это программное решение для генерации документации является де-факто лидером. Но у меня сложилось другое мнение.
В качестве разметки используется JSON. Проект имеет свой редактор (http://editor.swagger.io/ ^[5]). Сейчас доступен редактор версии 2.0.
Пример отображения можно увидеть по ссылке: petstore.swagger.io ^[6]
К преимуществам просмотрщика можно отнести возможность воспроизведения документации с удаленных ссылок.
При отображении документации, существует форма для отправки тестового запроса со своими параметрами.

www.apiary.io ^[7]
Apiary использует в качестве разметки API blueprint, разработанного на базе синтаксиса Markdown. Файл с документацией поддерживается редакторами для Markdown.
Проект имеет хороший онлайн редактор. Заметны баги с версткой сайта, в некоторых местах она недостаточно продумана. Тем не менее, смотрится значительно приятнее Swagger (но это — моя субъективная оценка).
Поддерживает генерацию промеров запроса для языков: Java, Javascript, Node.js, Perl, Python. PHP, Ruby, Go, C#, Visual Basic, Groovy, Objective-C, Swift.

Бонус: вы пишете свой проект и размещаете его на github? Тогда ваше RESTful API и SDK под него уже доступны на www.sdks.io ^[8]. Этот сервис регулярно отслеживает появление новых файлов с RESTful API и автоматически генерирует SDK библиотеки под них.

На сегодняшний день существует не менее 20 различных программных решений с различной функциональностью для RESTful API. Суть этой статьи была дать краткий обзор лидеров этого сегмента. Если вам интересно изучить эту тему глубже, можете ознакомится с другими моими статьями по этой тематике:

• Почему не стоит использовать Swagger как сервис для документирования RESTful API? ^[9]
• Перечень сервисов для документирования RESTful API ^[10]
• Автоматическая генерация SDK для RESTful API ^[11]
• Сравниваем форматы для документирования RESTful API: WADL, Swagger, I/O Docs, API BluePrint, RAML, Google API Discovery, Apimatic ^[12]

Автор: coolweb

Источник ^[13]