diff -r b5d11572f1ed -r 672e3c4bbd0c design/api/README.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design/api/README.md	Mon Jul 17 14:13:32 2017 +0200
@@ -0,0 +1,35 @@
+# Generation of API documentation
+
+The documentation use the api blueprint format ([documentation](https://apiblueprint.org)).
+
+[Aglio](https://github.com/danielgtaylor/aglio) is used for rendering the documentation into html.
+
+## install Aglio
+
+```bash
+$ npm install
+```
+
+### Available commands
+
+- Build the documentation (file metacategory.html)
+```bash
+$ npm run build
+```
+
+This runs the following command:
+```bash
+$ aglio -i metacategory.apib -o metacategory.html
+```
+
+- Watch the documentation.
+```bash
+$ npm run watch
+```
+
+This runs the following command:
+```bash
+aglio -i metacategory.apib -s
+```
+
+