OpenSlides/docs/interfaces/how-to.txt
2020-03-09 14:52:20 +01:00

69 lines
2.3 KiB
Plaintext

## How to specify an interface for a service?
There are many ways to describe, what a service should do. The main
characteristics (from an outside-view) are the provided functions. Each service
does have functions to execute with arguments and return types. Next to the
returnvalue, events can be published or errors be thrown. The way we want to
derscribe these interfaces is through a TypeScript-like interface definition.
The interface is the collection of all functions defined.
Example:
/**
* The Exception, if a model wasn't found. The missed id is given.
*/
Exception ObjectNotFound(id: Id);
/**
* Does something..
*
* @throws ObjectNotFound
do_it(data: MyRequest): void publishes MyEvent;
Interface MyRequest {
id: Id;
text: string;
some_other_value: number;
}
Event MyEvent on topic MyEventTopic {
changed_text: string;
}
There are some common types defined here:
Type Position=number;
Type Id=number;
Type Fqid=string; // `collection/id`
Type Fqfield=string; // `collection/id/field`
Type Collection=string; // `collection`
Type CollectionField=string; // `collection/field`
Type Model=object;
Type Field=string;
Type Value=any;
The language is a bit modified:
1) Exceptions
Exceptions should be declared by giving the name and parameters:
# Exception <name>(<param1>: <type1>, ...);
A comment should state, why this exception can be thrown
2) Events in the function declaration
Each function takes some arguments and have a return type. Next to the
return type, some events can be published. With the `publishes` token, one
can give a comma seperated list of events, that can be generated.
# my_function(): void publishes Event1, Event2
Events should be specified as interfaces, but named `Events`. Also there is
the `on topic` token, on which topic the message is broadcasted.
# Event MyEvent on topic MyEventTopic { ... }
3) Functiondocumentation
Each function must have a description. Also it should tell, what exceptions
could be thrown.
4) Placeholders
If you need generic names, use placeholders: `<my_placeholder>`
E.g. if the event topic is specific for one id, the topic used may be
definied as this example:
# Event MyEvent on topic MyEventForUser<user_id> { ... }