From: Ben Beltran <redacted>
Date: Sat, 5 Sep 2015 22:32:27 +0000 (-0500)
Subject: Adds api notation post
X-Git-Url: https://git.r.bdr.sh/rbdr/r.bdr.sh/commitdiff_plain/43a46e6a9544dcd6bdb3240997a09ea1ca6cefbf?hp=-c

Adds api notation post
---

43a46e6a9544dcd6bdb3240997a09ea1ca6cefbf
diff --git a/jekyll/_posts/2015-09-05-api-notation.md b/jekyll/_posts/2015-09-05-api-notation.md
new file mode 100644
index 0000000..52e2fc8
--- /dev/null
+++ b/jekyll/_posts/2015-09-05-api-notation.md
@@ -0,0 +1,47 @@
+---
+layout: post
+title: "API Notation: A simple way to document your libraries' contracts"
+tags: english specs
+color: purple
+header_image: api-notation.gif
+description: "API notation is a simple way to document the public
+contract of your componentsA"
+---
+
+When writing specifications and trying to figure out how components will interact, an important part is to define the public API as the contract others can depend on: So if you have a complex feature where several people are collaborating, you can ease up the integration woes by properly defining the contract they'll be using to communicate. This means that I usually end up having to write APIs in text files constantly, and over the years I've come up with a notation for this.
+
+The API notation is very simple and encodes what public properties, methods and events an object/class provides. It looks like this:
+
+```
+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
+->() callback return
+[xx] optional
+<xx> data type
+
+Recommended order: class first, then sockets, then instance. Internally: Properties, events, methods.
+
+// Anything after two forward slashes is a comment
+```
+
+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. 
+
+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.
+
+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.
+
+[vim]:  https://github.com/rbdr/api-notation.vim
+[atom]: https://github.com/rbdr/api-notation-atom
+[sublime]: https://github.com/rbdr/api-notation.tmLanguage
\ No newline at end of file
diff --git a/jekyll/img/headers/api-notation.gif b/jekyll/img/headers/api-notation.gif
new file mode 100644
index 0000000..3825533
Binary files /dev/null and b/jekyll/img/headers/api-notation.gif differ