git.r.bdr.sh - rbdr/r.bdr.sh/blob - jekyll/_posts/2015-09-05-api-notation.md

   1 ---
   2 layout: post
   3 title: "API Notation: A simple way to document your libraries' contracts"
   4 tags: english specs
   5 color: purple
   6 header_image: api-notation.gif
   7 description: "API notation is a simple way to document the public
   8 contract of your components"
   9 ---
  10
  11 When writing specifications and trying to figure out how components will interact, an important part of my workflow is to define the public API as the contract others can depend on: So if we have a complex feature where several people are collaborating, we can ease up the integration woes by properly defining the methods, properties and events they'll be using to communicate. This means that I usually end up having to write APIs in spec files constantly, and over the years I've been using and developing a notation for this.
  12
  13 The API notation is very simple and encodes what public properties, methods and events an object/class provides. It looks like this:
  14
  15 ```
  16 NameOfClass.WithPossibleNamespace
  17    + class property
  18    - instance property
  19   ~> listened events (socket)
  20   +> listened events (class/module)
  21   -> listened events (instance)
  22   <~ dispatched events (socket)
  23   <+ dispatched events(class/module)
  24   <- dispatched events (instance)
  25   :: class method
  26    # instance method
  27
  28 Other symbols
  29   => returns
  30 ->() callback return
  31 [xx] optional
  32 <xx> data type
  33
  34 Recommended order: class first, then sockets, then instance. Internally: Properties, events, methods.
  35
  36 // Anything after two forward slashes is a comment
  37 ```
  38
  39 That's it. This simple notation lets us quickly define what an object or class looks like, and what data types we can expect from methods, properties and events. It's a notation that's easy to put inside documents, and it's easy to parse. The origin of the symbols is kind of a mixed bag and I've been developing based on some languages I've used. The `-` and `+` for properties come from Objective C, and the `#` and `::` for methods come from ruby. The `<` and `>` in events define the direction of the flow (outgoing or incoming), and the `~` for socket events is an attempt to simulate the thunderbolt symbol  used in network diagrams.
  40
  41 If you find yourself constantly having to write APIs for your components, and would like to have an easy way to add them to your documents (especially plain text / markdown documents), give it a try. You can use syntax highlighting in [vim][vim], [atom][atom], or [sublime text][sublime] by creating files with the `.api` extension.
  42
  43 If you do decide to give it a try, let me know how it works out for you and if there's any cases you think it doesn't work with. It's constantly evolving to reflect the types of applications I've had to create, so any other cases that may help to get this further are welcome.
  44
  45 [vim]:  https://github.com/rbdr/api-notation.vim
  46 [atom]: https://github.com/rbdr/api-notation-atom
  47 [sublime]: https://github.com/rbdr/api-notation.tmLanguage