Package: urest-mp
uRESTBackgroundThis library is designed to enable simple API's to be built on
micro-controllers, based on a sub-set of the REST API design principles, and
inspired by the design of theApollo
DSKYguidance computer.
Rather than build a full HTTP server stack, including JSON parser, and
supporting the full complexity of modern REST API's, this library aims to
support simple operations in a resource constrained environment.Like the DSKY unit, it is assumed that all the 'objects' representing the states
we are interested in are held in
'nouns'. The HTTP actions
then represent 'verbs' which dictate the actions on the noun. So each API call
is then in the form of 'verb-noun'; e.g. 'GET /led', or 'PUT /led'. Valid verb
actions areVerbHTTP MethodActionGetGETReturn the current state of the requested noun.SetPUTSet the requested noun toexactlythe specified state. This is assumed to be idempotent, with the resultant state matching exactly the request from the client.UpdatePOSTUpdate the state requested noun. This isnotassumed to be idempotent: for instance asking a noun to move between two states on each update.DeleteDELETERemove the current state of the noun, and return to a the default state. This doesnotremove the noun from the API: only the state currently held by the API.In all cases the body of the HTTP request is a simple collection of 'key: value'
pairs, formatted as aJSONobject. Only a
sub-set of the JSON specification is used: in particular multiple objects are
not allowed, and nor are arrays (i.e. '[]') of any sort. This both simplifies
the parsing, and especially the memory required for the parser, and reinforces
the intent to support only minimal API's.InstallationA package of this library is provided on PyPi asurest-mp. This can be installed with the
normal Python tools, and should also install to boards runnning MicroPython
underThonny.For manual installation, everything under theurestdirectory should be copied
to the appropriate directory on the MicroPython board, usually/lib. The
library can then be imported as normal, e.g.python from urest.http import RESTServer from urest.api import APIBaseSee the documentation for theexamplesfor more
detailed guidance on the use of the library. This code is also available in theurest/examplesfolder, or as the libraryurest.exampleswhen the package is
installed.DebuggingConsole output from theurest.http.server.RESTServeris controlled by the
standard__debug__flag. By default no output will be sent to the 'console'unlessthe__debug__flag isTrue.Note:that in the standard Python environments the status of the__debug__flag is often controlled by the optimisation level of the interpreter: see the
standardPython documentationfor more details. For MicroPython the status of the__debug__flag is set byinternal constants.
However if the__debug__constant is set whilst a programming is running theresults may be unexpected,
due to optimisations undertaken by the MicroPython lexer. Instead for MicroPython set
the status of the__debug__flag in the platform standardboot.pyor
similar: see the documentation for the specific port for more details.DesignThe core of the library is a simple HTTP server, specialised to the delivery of
a REST-like API instead of a general HTTP server. The design, and the use of theasynciolibrary, is inspired by theMicroPython HTTP
Serverby Erik de
Lange. This library uses a roughly similar structure for the core of theasyncioevent loop, and especially in the design of theRESTServerclass.Key differences includeSupport forPUT,POSTandDELETEoperations, in addition toGET.
These are required for an API server, and also form the 'verbs' of the actions
allowed on the 'nouns' by the API built on-top of this library.A more object-oriented design of the call/response handler, made easier this
library isnota general HTTP server. For instance Pythongettersandsettersare used where possible for input validation, and the central API
response is based on theAPIBaseabstract base
classA more explicit validation of input from the network layer, especially in
the assumption that all input is by default hostile. This library should serve
as an example of best-practice in protocol handling; at least in the slightly
resource constrained environment of MicroPythonThis implementation is principally a teaching library, so theDocumentationshould be at least as
important as the 'code'. Where possible all algorithms and implementation
techniques should also be explained as fully as possible, or at least linked to
reference standards/implementationsFor consistency, all code should also be in the format standardised by theBlacklibrary. This makes it easier to
co-ordinate external code and documentation with the implementation documented
here.Known ImplementationsRaspberry Pi Pico W (MicroPython 3.4)