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


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

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

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


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


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


    www.apiary.io
    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. Этот сервис регулярно отслеживает появление новых файлов с RESTful API и автоматически генерирует SDK библиотеки под них.

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

    Средняя зарплата в IT

    110 000 ₽/мес.
    Средняя зарплата по всем IT-специализациям на основании 8 477 анкет, за 2-ое пол. 2020 года Узнать свою зарплату
    Реклама
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее

    Комментарии 16

      +4
      Буквально вчера искал что-то для себя и мне понравился вот этот инструмент apidocjs.com. Умеет генерировать приятную на глаз документацию прямо из комментариев к иходному коду (phpDoc).
        +2
          0
          Тотально согласен — 2017г и RAML активно развили до версии 1.0
          Запрогал авто-генератор для Laravel, с поддержкой JSON API — https://github.com/RJAPI/raml-json-api
          (Контрибы и предметная критика приветствуется)

          PS Insanity is doing the same thing over and over again, expecting different results. Albert Einstein
          По сему коллеги — давайте перестанем «кодить» свои велосипеды и начнем работать с качественными форматами представления входных/выходных данных и их описанием. (нисколько не отменяет попыток изобретать что-нибудь новое, академически весомое)
          +1
          Вопрос тем, кто использовал Swagger 2.0 и RAML. В чём их принципиальное отличие друг от друга? Какая из спецификаций охватывает большее число возможных кейсов (например, возможность явно указывать протокол)?
            +1
              0
              О, спасибо! очень крутая штука
                0
                Если будете делать что-то, напишите мне.
                Мы давно хотим перевести наш АПИ с html файликов, на что-то такое, но руки всё не доходят.
                0
                Вы спасли мне жизнь :)
                Лучшее из всего, что мне попадалось. Как всегда — просто тихим комментарием на гитхабе.
                0
                Ещё есть jsondoc.org/
                  +23
                  Впечатляющая подборка. Целых два средства для описания RESTful API!
                    +1
                      0
                      Тоже покадал на этот ресурс. Думаю, он будет хорошим дополнением к разработанному апи.
                        0
                        1 проект я уже пропустил через этот сервис (iOS + php). Очень удобный :)
                      +1
                      А можно кратно объяснить что это такое вообще и зачем оно нужно? Есть же ASN1 — стандарт описания интерфейсов с кучей написанных генераторов под какие угодно языки программирования?
                        +1
                        А какие вообще стандарты / нотации описания интерфейсов бывают? Для бизнес аналитика, системного аналитика.
                          –1
                          Как обычно, в комментариях намного больше интересного, чем в статье.

                          P.S. Статья не плохая, просто такова специфика Хабра

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

                          Самое читаемое