[asterisk-commits] dlee: branch dlee/stasis-http r382602 - /team/dlee/stasis-http/res/

[SVN commits to the Asterisk project]

Author: dlee
Date: Thu Mar  7 10:34:11 2013
New Revision: 382602

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=382602
Log:
File docs for res_stasis_http

Modified:
    team/dlee/stasis-http/res/res_stasis_http.c

Modified: team/dlee/stasis-http/res/res_stasis_http.c
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-http/res/res_stasis_http.c?view=diff&rev=382602&r1=382601&r2=382602
==============================================================================
--- team/dlee/stasis-http/res/res_stasis_http.c (original)
+++ team/dlee/stasis-http/res/res_stasis_http.c Thu Mar  7 10:34:11 2013
@@ -19,8 +19,50 @@
 /*! \file
  *
  * \brief HTTP binding for the Stasis API
- *
  * \author David M. Lee, II <dlee at digium.com>
+ *
+ * The API itself is documented using <a
+ * href="https://developers.helloreverb.com/swagger/">Swagger</a>, a lightweight
+ * mechanism for documenting RESTful API's using JSON. This allows us to use <a
+ * href="https://github.com/wordnik/swagger-ui">swagger-ui</a> to provide
+ * executable documentation for the API, generate client bindings in different
+ * <a href="https://github.com/asterisk/asterisk_rest_libraries">languages</a>,
+ * and generate a lot of the boilerplate code for implementing the RESTful
+ * bindings. The API docs live in the \c rest-api/ directory.
+ *
+ * The RESTful bindings are generated from the Swagger API docs using a set of
+ * <a href="http://nedbatchelder.com/code/cog/">Cog.py</a> templates. Cog.py is
+ * extemely lightweight (maybe too lightweight), and can be installed easily
+ * using \c pip. Template scripts live in the \c cog/ directory, and the
+ * generated code lives in the \c res/stasis-http/ directory.
+ *
+ * The structure of the generated code is:
+
+ *  - A tree of \ref stasis_rest_handlers which are used for request routing.
+ *  - Prototypes for request handlers, and structures for passing arguments in
+ *    the request handler.
+ *  - A set of \ref stasis_rest_callback functions, which glue the two
+ *    together. They parse out path variables and request parameters to populate
+ *    a specific \c *_args which is passed to the specific request handler.
+ *
+ * The use of the generated \c *_args allows for greater type safety and reduced
+ * boilerplate in the request handlers themselves.
+ *
+ * The basic flow of an HTTP request is:
+ *
+ *  - stasis_http_callback()
+ *    1. Initial request validation
+ *    2. Routes as either a doc request (stasis_http_get_docs) or API
+ *       request (stasis_http_invoke)
+ *       - stasis_http_invoke()
+ *         1. Further request validation
+ *         2. Routes the request through the tree of generated
+ *            \ref stasis_rest_handlers.
+ *         3. Dispatch to the generated callback
+ *            - \c stasis_http_*_cb
+ *              1. Populate \c *_args struct with path and get params
+ *              2. Invoke the request handler
+ *    3. Validates and sends response
  */
 
 /*** MODULEINFO