REST API spindle extends the gateway with a http(s) service endpoint which maps valospace resources to a RESTful API using a reusable declarative route mapping definition JSON-LD document.
Once a well-defined mapping definition for some use case is created and documented by a technician then all valonauts are able to create conforming resource structures fully inside the valospace. After that a service provider can be commissioned to expose those resources via some internet endpoint using the mapping definition.
This document is the introduction document of the spindle @valos/rest-api-spindle and part of the domain @valos/kernel.
The current implementation is a working prototype. The core is structurally sound but messy and there's little in the way of specification. There's also some abstraction leakage; the JSON schema is fixed at what the underlying fastify web server consumes.
As is traditional the rest api spindle web service is defined as a set of route patterns which are matched against incoming request IRIs.
The mapping definition is JSON-LD document (created by a technician) which describes a set of routes and their mapping vpaths to valospace resources. These paths typically originate from a single, configurable service index valospace resource.
A well-defined and documented mapping definition for some use case can be reused. A valonaut can create a conforming valospace service index and its surrounding resource structure and then request for a service from a rest API provider by providing only the mapping definition, the service index and any necessary security credentials.
The route definition format is JSON schema which is as expected used to describe the route request and response data types. These route specs can optionally exposed via an OpenAPI 3.0.0 (or newer) route). In addition to route format specification the definition schema includes the declarative mapping definitions from the route requests to valospace resources and eventually back to responses.
The sub-library schema-builder contains the convenience functions that can be used to build the schema description types and routes and also emit the plain data description objects which the rest api spindle can then consume.
This package is a major study on whether REST API <-> ValOS mappings for a particular domain can be specified in a fully declarative fashion. Reaching this goal would have several desirable qualities:
Taken further, purely declarative mappings can allow REST API endpoints be opened fully from inside valospace. A well-designed Relation-based specification scheme can make route exposition a near trivial matter of instructing a worker group to "open all routes that are specified to start from this resource when used as the route root".
Purely declarative mappings provide a stronger foundation for introspection, debugging and validation of the mappings in general and particular requests in specific, at least on the fabric side.
The no-code aspect can allow for local inspire rest-api-spindles. These spindles can collaboratively intercept remote REST API GET calls and then opportunistically serve them locally. This can be done if the remote endpoint is known to be a rest-api-spindle and if all data is locally available. If implemented well this allows trivial web apps to rely on naive REST API interaction flows without having to care about minimizing the number of requests or roundtrips.
The biggest design feature to reduce the need for multitude of mappings is the subject paths. Using subject paths a particular common mapping use case can specify an well-known ordered index partition structure and the rest-api-spindle compatible mapping route specification for it sans route root resource. Then the different use cases can specify their mappings solely in terms of the endpoint prefix, the mapping root resource id and the identifier of the above mapping route spec.
All routes share common as well as separate characteristics. The handler of a request is located using the most specific route config which matches the request IRI and its HTTP method. The route config specifies the route *category* which when combined with the request method uniquely specifies the actual route type and thus the handler callback.
A route mapping is defined in terms of the service index resource, a route path from it to a route root resource and zero to many runtime paths and their associated runtime resources
The mapping rule semantics for the shared service index resource and for the individual route paths and route root resources are uniform. These are all preloaded during service initialization. Conversely the semantics of a runtime path and runtime resources depends on the route type. As these paths and resources depend on request parameters they are loaded dynamically during request resolution.
The *service index resource* is statically configured and should be the same for all routes starting from the same public endpoint. This index resource is typically the root entity of the service master index partition. The route paths (and some of their runtime paths) are then typically defined as relations and references in the index partition.
The subject path is a path from the root resource to the subject resource. The subject resource is the immediate _parent_ resource of the route runtime parts. Its role is to act as the local index entry point to the route runtime resources. The subject resource is preloaded and mostly static. But because the subject path is a live kuery the subject resource does change if the subject path resources and fields themselves change.
The runtime paths and resources if any, are determined by the handler which handles the particular request. They are based on the route configuration and can depend on the request route, query and other parameters. They use the route subject resource as their head.