💾 Archived View for gemini.unlimited.pizza › api.gmi captured on 2024-02-05 at 09:33:07. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅️ Previous capture (2023-11-04)

➡️ Next capture (2024-06-20)

-=-=-=-=-=-=-

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>)