OpenSlides/docs/interfaces/how-to.txt

## 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> { ... }