You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
20 lines
2.7 KiB
Plaintext
20 lines
2.7 KiB
Plaintext
General architecture of the internal API
|
|
========================================
|
|
|
|
The API implementation consists of a number of different things:
|
|
- System interaction libraries, often wrappers around system management programs
|
|
- Data sources, a standardized representation of the data exposed by those libraries
|
|
- Types, different kinds of 'system objects' (storage drive, block device, LVM volume group, etc.) that can be read from and interacted with
|
|
- A root API schema, which represents the 'tree' of available queryable objects
|
|
|
|
The full API schema is made up of the root schema + the schemas of each type. Types can reference each other, including recursively, so loops in the schema exist. The API uses dlayer as its querying mechanism.
|
|
|
|
A 'data source' is a factory function that produces a data retrieval function. This data retrieval function accepts an array of object IDs (or a special `All` marker), and is expected to produce a respectively-ordered array of results. The data retrieval function is responsible for doing the entire translation from this standardized retrieval API, to whatever API the underlying system interaction library requires. The `dataloader` library is used to wrap this data retrieval function for more efficient operation.
|
|
|
|
Each type is defined as an object with a set of keys, whose value is a function that (optionally) accepts an object of named arguments and a context object as its parameters, and which is expected to (asynchronously) return a value for that key. All the previously-defined-and-wrapped data sources are made available under `sources` on the context object. The context object also includes a number of utility functions for evaluating other properties, for edge-cases where the logic of one property is dependent on the value of another. These functions are free to implement whatever logic they require, and in fact this uses the same API as the rest of dlayer - 'types' are not actually special on a dlayer level, they are essentially just lazily-returned schema objects.
|
|
|
|
In this project, specifically, most properties *are not* defined manually - instead, `dlayer-source` is used, which provides a bridge between dlayer and the data sources mechanism. Rather than manually calling a source for every property that needs to access it, a `$sources` meta-property is defined that specifies every data sources that's needed for this object, and which properties it can satisfy. The value for those property keys may either be a function (to manually extract data from the data-source-provided value) or a string (to simply copy the key from the data-source-provided value).
|
|
|
|
Data source: ID[] -> DataObject[]
|
|
Schema: QueryObject -> (data source) -> SchemaObject[]?
|