6. REST¶

6.2.1. REST 2.0: приложения RestMultipart и RestFlowMod¶

6.2.1.2. Архитектура сервиса¶

Пути для обращения к API формируется следующим образом:

• http://{{host}}/api/<app_name>/<parameters>

• Примеры:

  • GET: http://{{host}}/api/rest-multipart/port/{{dpid}}/all
  • GET, POST: http://{{host}}/api/rest-multipart/flow/{{dpid}}
  • POST: http://{{host}}/api/rest-flowmod/flowentry/
  • DELETE: http://{{host}}/api/rest-flowmod/flowentry/clear/{{dpid}}

Записи вида {{variable}} – синтаксис обозначения переменных в Postman. Чтобы сформировать html-запрос, подставьте на их места конкретные значения. Примеры этих значений Вы найдете в нашей коллекции запросов.

6.2.1.3. Postman collection¶

Postman collection:

• link: https://www.getpostman.com/collections/34a4933f146bee7383d9
• file: RuNOS_REST_2.0.postman_collection.json

Environment: RuNOS_REST_2.0.postman_environment.json

6.3.1. Концепция REST-интерфейса в RuNOS¶

Предположим, Вы хотите написать приложение, которое будет конструировать новые потоки (flow entries) на подключенных к контроллеру switch’ах. Далее будем называть его MyApp. В таком случае у Вас 2 пути:

• Получать параметры на этапе запуска контроллера (и далее работать автономно). Тогда Вашему приложению нужна лишь своя секция в конфигурационном файле network-settings.json.

• Получать параметры в runtime. В этом случает RuNOS предлагает Вам 2 варианта интерфейсов:

  • Web UI

  • REST API

    Пользователь посылает Вам простой html-запрос (GET, POST, PUT, DELETE), а Вам остается лишь среагировать на него.

Предположим, Вы выбрали rest.

6.3.2. Пример rest-запроса к приложению¶

Рассмотрим последовательность действий, отвечающих использованию rest-интерфейса. Мы начнем с отправки пользователем rest-запроса и закончим отправкой контроллером ответа на него.

• Пользователь составляет запрос:

  curl http://127.0.0.1:8000/api/my-app/flowentry/ -XPOST -d'{
        "eth_src": "11:11:11:11:11:12",
        "ip_src": "192.168.0.1",
        "modify_eth_src": "22:22:22:22:22:22",
        "out_port": 1}'
  

  Здесь:

  • 127.0.0.1:8000 – путь к TCP-серверу контроллера,

  • api – пользователь обращается к REST API контроллера,

  • my-app – rest-name Вашего приложения (см. Добавление поддержки REST в Ваше приложение),

  • следом за my-app может идти любой путь, который Вы обозначите как допустимый:

    MyApp::init::acceptPath(Method::POST, "flowentry");
    

  • На месте flowentry может стоять любое корректное регулярное выражение. Так же метод acceptPath может вызываться несколько раз, тем самым задавая множество обрабатываемых путей.

• Сформированный запрос поступает на TCP server, управляемый приложением RestListener. RestListener проверяет корректность запроса и, в случае успеха, распарсит запрос на параметры и отправит его в соответствующее приложение.

  Примечание

  Для этого Вам нужно зарегистрировать Ваше приложение.

• Далее поток управления переходит к методу handlePost``приложения ``MyApp.

  json11::Json MyApp::handlePOST(std::vector<std::string> params, std::string body);
  

Здесь:

• params – это вектор строк, получаемый парсингом пути html-запроса,

• body – строка, содержащая в себе тело POST-запроса (“” для GET, DELETE). Вы можете распарсить ее в json:

  json11::Json::object req = json11::Json::parse(body, forErr).object_items();
  

• Ваше приложение выполняет необходимые манипуляции и возвращает ответ в формате json,

• RestListener,

• пользователь получает ответ.

6.3.3. Добавление поддержки REST в Ваше приложение¶

Если говорить коротко, то в Runos “добавить в приложение поддержку rest” значит добавить в список родительских классов Вашего приложения класс RestHandler и реализовать его виртуальные методы. Далее мы рассмотрим этот процесс подробно.

• Добавьте REST в ваше приложение:

  #include "Rest.hh"
  #include "AppObject.hh"
  #include <string>
  
  class MyApp : public Application, RestHandler {
      std::string restName() override { return "my-app"; }
      std::string displayedName() override { return "My beautiful application"; }  // web name
      bool eventable() override { return false; }
  
      json11::Json handleGET(std::vector<std::string> params, std::string body) override;
      json11::Json handlePOST(std::vector<std::string> params, std::string body) override;
      // also handlePUT and handleDELETE
  }
  

• зарегистрируйте rest-handler в методе MyApp::init:

  RestListener::get(loader)->registerRestHandler(this);
  

• определите множество URL, обрабатываемых Вашим приложением в методе MyApp::init:

  acceptPath(Method::GET, "switches/[0-9]+");  // handle GET request with path /api/my-app/switches/
  acceptPath(Method::POST, "[A-Fa-f0-9:-]");  // handle POST request with path /api/my-app/mac/
  

• в методе MyApp::handleGET происходит вся существенная обработка входящих HTTP-GET запросов. Логику работы Вашего приложения с rest-запросам (GET) Вы определяете именно в нем.

• Готовый пример реализации rest-интерфейса Вы можете посмотреть, например, в классе StaticFlowPusher или в RestMultipart / RestFlowMod.

6.3.4. Event model¶

В RuNOS реализована т.н. event model. Она позволяет получить отчет о действиях приложений за определенный период времени. Например, curl {{host}}/timeout/switch-manager/0/ выдаст лог событий, произошедших в приложении Switch Manager с момента запуска (0).

Вы можете добавить поддержку event model в свое приложение, назначив метод eventable возвращать true (как не сложно догадаться, false будет означать отсутствие поддержки event-model):

bool eventable() override { return true; }