[rbdr/r.bdr.sh] / api.gmi

--- title: /api.html
--- description: API Notation
## API Notation

API Notation is a language-agnostic notation to share the public API of components in code. It was created to standardize software specification documents in teams that need to review code across several languages.

## Reference
The notation allows describing objects or modules, with properties, events and methods along with their types.
```
// Anything after two forward slashes is a comment
NameOfClass.WithPossibleNamespace
   + class property
   - instance property
  ~> listened events (socket)
  +> listened events (class/module)
  -> listened events (instance)
  <~ dispatched events (socket)
  <+ dispatched events(class/module)
  <- dispatched events (instance)
  :: class method
   # instance method
----
Other symbols
  => returns
  #> throws
[xx] optional
<xx> data type
```

## Example
With this artificial example, you can see how to use it for more complex cases:

```
// Definitions start with object / module / class names, with namespaces
// separated by periods. Types are marked between angular brackets.
Definitions.Models.Post
  // Properties.
  +static_property &lt;Type>
  -instance_property &lt;Types&lt;Can&lt;Be&lt;Nested>>>>
  // Methods. Parameters are listed in parentheses, and comma separated.
  // Optional values are inside brackets
  // => defines return values
  // #> defines thrown exceptions, can be comma separated.
  ::static_methods(parameter_label &lt;Type>) => ReturnValueType #> BadTimesException,UnknownError
  #update(text &lt;String>, [options] &lt;GlobalOptions.tOptions>) => Promise&lt;Void>
  // Function types can include parameter lists, returns and throws as well.
  #transform&lt;T>( Function&lt;T>(payload &lt;T>) => &lt;T>, announce &lt;Bool>) => &lt;Bool>
  // Listened Events
  +>static_listener(parameters_expected &lt;Bool>)
  ->instance_listener()
  ~>network_events(peer &lt;Networking.Peer>)
  // Emitted Events
  &lt;+emitted_statically(payload &lt;StaticEventPayload>)
  &lt;-emitted_by_instance(reason &lt;String>, code &lt;Int>)
  &lt;~emitted_through_network(text &lt;String>)
```