Skip to content

wrench daemon: REST API Development and Integration

Jump to bottom
Henri Casanova edited this page Jan 18, 2023 · 8 revisions

Overall Aim

Develop a REST API for (a subset of) WRENCH, and a Python API on top of it.

Current Status as of 01/18/2023

  • There is a working toy implementation of the REST API in the wrench-daemon branch of the wrench repository,
  • There is a working toy implementation of the Python API in this repository

Downsides:

  • The REST API is completely ad-hoc, and the wrench-daemon uses httplib, which is pretty low-level
  • The documentation is generated completely ad-hoc using a bunch of weird ad-hoc scripts

As expected, techniques exist for REST API generation/documentation, etc. As a first step, there is a wrench-openapi.json file in tools/wrench/wrench-daemon/doc that defines a good (but small) REST API for WRENCH using the OpenAPI format. To look at the documentation:

  • Go to https://editor.swagger.io/
  • Erase the sample text there
  • Copy-and-Paste the content of file wrench-openapi.json in there
  • Annoyingly, the content will be displayed in YAML, not JSON
  • In there, you can modify/tweak anything you want
    • For instance, to create a new path, just copy-and-paste one and modify the copy
  • On the right, you see the beautiful generated documentation
  • You can export it back to JSON ("Convert and save as JSON")

Now, there is NO CONNECTION right now between the content of this JSON file and what's actually implemented. The JSON is a standard (and automatically documented) was of describing a REST API, and the REST API that is implemented is totally ad-hoc. That should change.

Project Objectives

Here are the project objectives, broadly speaking:

  1. Move away from httplib and instead use CrowCPP: https://github.com/CrowCpp/Crow, so that it's less code to create/add routes and so that more dynamic routes can be created
  2. Specify the REST API using the OpenAPI Format, and have the automatically-generated (by Swagger) documentation added to the WRENCH on-line documentation
  3. Implement the REST API clien/server side following the OpenAPI API specification

2 and 3 are key. 1 is not technically necessary, but could be super-nice. Let's go for it for now and see what happens.

1. Use CrowCPP

  • Look at CrowCPP at https://github.com/CrowCpp/Crow
  • Play with it to understand how it works by doing a small standalone example
  • Note that the specification in wrench-openapi.json has routes in which, for instance, there is a simulation ID as part of the route. This is currently not doable in our bare-bone implementation that does not use CrowCPP. We were told that with CrowCPP this could be done easily, which should be verified
  • Create a branch wrench-daemon-crowcpp off the wrench-daemon branch
  • Replace a route that exists in the current API (initSimulation?) using CROW, and see if it works
    • Likely just comment-out all other routes to make it easy
  • If all the above seems to work, then decide if it's worthwhile to move over to CrowCPP (most likely yes)
  • If deemed worth while then go for it and replace all current routes in the same manner in the wrench-daemon-crowcpp branch
  • When done, merge is all back into the wrench-daemon branch

2. Update the REST API and Python API

  • Update the code and/or OpenAPI Specification so that they match
    • Right now the OpenAPI specifies (I think) way more than that the code actually does
  • Update the Python API Accordingly

3. Evolve the REST API and Python API

  • Define what new things to add to these APIs, and add them, until the end of the project
Clone this wiki locally