69 lines
2.3 KiB
Plaintext
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> { ... }
|