146 lines
5.5 KiB
Plaintext
146 lines
5.5 KiB
Plaintext
/**
|
|
* SyntaxError is returned, when the syntax of the request body is wrong.
|
|
* This error is returned on the beginning of a request with http-status-code
|
|
* 400.
|
|
*/
|
|
Exception SyntaxError(msg: string);
|
|
|
|
/**
|
|
* JsonError is returned, when the body does not contain valid json. This error
|
|
* is returned on the beginning of a request with http-status-code 400.
|
|
*/
|
|
Exception JsonError(msg: string);
|
|
|
|
/**
|
|
* ValueError is returned, when the value of a field does not have the expected
|
|
* format. E.g. there is an indicated relation to a key, but the data are no
|
|
* foreign ids/fqids. The exception may happen, if the stream is used at
|
|
* runtime, because this cannot be detected when the caller makes the request.
|
|
*/
|
|
Exception ValueError(msg: string);
|
|
|
|
/**
|
|
* InternalError is an unexpected error on the server side. When it happens at
|
|
* the beginning of a request, an http-status-code 500 is used. But it can also
|
|
* happen after the first data have been streamed to the client. The error does
|
|
* not contain any useful information. More information can be found in the
|
|
* server log. This is the only error that generates a server log message.
|
|
*/
|
|
Expection InternalError(msg: string);
|
|
|
|
/**
|
|
* This methods subscribes to a list of given request. The response is a stream
|
|
* (language dependent) updating all models according to the ModelRequest if new
|
|
* data is available. On subscription, initial data must be pushed to the caller
|
|
* as soon as possible. The stream can be closed by closing the stream (e.g. the
|
|
* underlying network connection).
|
|
*
|
|
* @throws SyntaxError
|
|
* @throws JsonError
|
|
* @throws ValueError
|
|
* @throws InternalError
|
|
*/
|
|
subscribe(request: ModelRequest[]): stream<ModelData>;
|
|
|
|
/**
|
|
* This is the main interface for requesting models in a structured, nested way.
|
|
* The initial request targets some models as the root models of one collection
|
|
* with all the same fields. This build a tree of dependencies, because the
|
|
* value of some fields may be a GenericRelationFieldDescriptor again.
|
|
*
|
|
* For a description of `fields` and `collection`, see
|
|
* GenericRelationFieldDescriptor and RelationFieldDescriptor.
|
|
*
|
|
* `ids`: This is a list of ids for a collection, that should be provided. All
|
|
* models, that the user can see, must be included in the response. The model
|
|
* fields are handled according to `GenericRelationFieldDescriptor`.
|
|
*/
|
|
Interface ModelRequest extends Fields {
|
|
ids: ID[];
|
|
collection: Collection;
|
|
}
|
|
|
|
Interface Fields {
|
|
fields: {
|
|
[field: Field]: GenericRelationFieldDescriptor
|
|
| RelationFieldDescriptor
|
|
| StructuredFieldDescriptor
|
|
| null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* For an overview, see `ModelRequest`.
|
|
*
|
|
* `fields` (inherited from `Fields`, see above):
|
|
* Regardless of the value of a field, the restricted values are given in the
|
|
* response (multiple for structured fields). If the restricted value is null,
|
|
* the field must be included here.
|
|
*
|
|
* If the value is not null, it is indicated, that there is a reference to
|
|
* follow. There are three types of values:
|
|
* - GenericRelationFieldDescriptor: The reference is a generic one. This means,
|
|
* that the actual value from the model is a fqid or an array of fqids.
|
|
* - RelationFieldDescriptor: A collection is given, so it can be expected, that
|
|
* the actual model value is an id or an array of ids.
|
|
* - StructuredFieldDescriptor: The field is a template field and should be
|
|
* handled in this way.
|
|
*/
|
|
Interface GenericRelationFieldDecriptor extends Fields {
|
|
type: 'generic-relation' | 'generic-relation-list';
|
|
}
|
|
|
|
/**
|
|
* For an overview, see `ModelRequest`. For `fields`, see
|
|
* GenericRelationFieldDescriptor.
|
|
*
|
|
* `collection`:
|
|
* This is the collection, the ids are associated to. The ids are provided with
|
|
* two different ways:
|
|
* - In a ModelRequest, the ids are given.
|
|
* - If this interface is used in a field indication a relation, the id(s) are
|
|
* given by the actual model data.
|
|
*/
|
|
Interface RelationFieldDescriptor extends Fields {
|
|
type: 'relation' | 'relation-list';
|
|
collection: Collection;
|
|
}
|
|
|
|
/**
|
|
* Structured Fields: A field with `$` as a placeholder can be structured. The
|
|
* `$` is a template placeholder. The `template field` holds a list of strings
|
|
* with options to insert into `$`. All these fields are the `structured
|
|
* fields`. Example:
|
|
* B_$_ids is the template field. Its value may be `["1", "test"]`, so the
|
|
* structured fields are B_1_ids and B_test_ids.
|
|
*
|
|
* This interface indicates, that there are structured fields related to the
|
|
* given template field, that should be resolved. If one would give `B_$_ids:
|
|
* null` without using this interface, the response would be just the template
|
|
* field `B_$_ids` and no structured fields.
|
|
*
|
|
* For just resolving values, leave `values` out (hence the optional parameter).
|
|
*
|
|
* For retrieveing a single structured field, use `RelationFieldDescriptor`. E.g.
|
|
* when trying to get the groups for a user from meeting 2, use `group_2_ids`
|
|
* directly and do not bother with structured fields. The terminology is a
|
|
* `specific structured field`.
|
|
*
|
|
* If the values of all structured fields are references, use the `values`
|
|
* parameter analog to the `fields` paramter as documented in
|
|
* `GenericRelationFieldDescriptor`.
|
|
*/
|
|
Interface StructuredFieldDecriptor {
|
|
type: 'template',
|
|
values?: GenericRelationFieldDescriptor | RelationFieldDescriptor;
|
|
}
|
|
|
|
|
|
/**
|
|
* This structure holds all data given by the called service as a map of
|
|
* fqfields to the fields values.
|
|
*/
|
|
Interface ModelData {
|
|
[fqfield: Fqfield]: Value;
|
|
}
|