REST API - chuckablack/quokka GitHub Wiki

The quokka server presents a REST API for communication from other entities, to quokka. These REST APIs include:

  • UI: There are a number of APIs - the bulk of them, actually - which serve to support communication between the quokka UI and the quokka server.
  • Device: Quokka has a couple APIs for 'heartbeat' style communication, from devices that must use alternate means of communication with quokka. I.e. quokka normally initiates requests via SSH or NETCONF, but if that is impossible (e.g. SDWAN devices communicating via the public Internet), then this HTTP-based communication via the Device API can be used.
  • Capture/Portscan/Traceroute: For the implementation of diagnostic functions such as packet capture, port scanning, or traceroute, a remote worker (i.e. not the quokka server) performs the task. The results of such functions - e.g. captured packets, or portscan/traceroute results - are communicated to the quokka server via these REST APIs.
  • Worker: Quokka keeps track of the status of remote workers mentioned above, via the remote workers sending heartbeat REST API requests (not unlike devices) to the quokka server. In addition, the 'commands' for remote workers to perform capture, portscan, or traceroute, may be communicated via these heartbeats.

The following image shows the REST APIs, also called "views" in software development terminology:

images/rest-apis.png

The Flask framework is fundamentally about the creation of a web service, and the ability to create REST endpoints that get called whenever somebody or something makes an HTTP request against Flask's web server.

The Flask documentation is pretty complete and thorough, so I won't recreate it here. However, I'll provide some information to get the ball rolling. Here are some basics:

  • Decorators: You use what are called "decorators", which are directives placed right above your REST endpoint definition, that tell Python the actual URI (e.g. "/ui/devices") that maps onto a specific endpoint implementation.
  • Endpoints: The endpoints themselves are just Python functions (e.g. "def devices():", with code to handle all the parts of the HTTP request.
  • Query parameters: Flask provides a way to get at the query parameters from the HTTP request, by referencing the request. In this way, we are able e.g. to get the ID or name of the device being requested, get the filter data for the packet capture, etc.

Note regarding capture/portscan/traceroute views: Be sure to understand the difference between the views that are used to initiate are retrieve capture, portscan, and traceroute operations, which are in the UI views, with the views used by workers for reporting data back from the packet capture or portscan or traceroute operation, which are in the views for those operations (e.g. capture_views.py is used by a remote worker to report captured packets to quokka, to be stored in the DB).

Benefits of this design for UI

One of the key advantages of this type of implementation regarding the UI-based REST calls, is that one can build the quokka UI using any technology desired - i.e. you do not need to use Flask to deliver web pages and the like. This mean that, as some have done, you can build your own UI on top of quokka, merely grabbing the data via the REST APIs for user interface functionality.

This decoupling of the UI from the server itself follows the pattern of loose coupling, which allows there to be multiple different implementations of the various parts (in this case UI vs server). In the future, I may even consider re-implementing the UI using something such as Angular, or a newer framework that may appear in the future.