Merge pull request #1153 from ltalirz/fix_issue_812_apidoc_for_rest

add API documentation for REST API

aiida/restapi/common/exceptions.py

@@ -12,8 +12,9 @@
 highest level, namely that of the interaction with the client. Their
 specificity resides into the fact that they return a message that is embedded
 into the HTTP response.
+
 Example:
-    .../api/v1/nodes/ ... (TODO compete this with an actual example)
+.../api/v1/nodes/ ... (TODO compete this with an actual example)
 
 Other errors arising at deeper level, e.g. those raised by the QueryBuilder
 or internal errors, are not embedded into the HTTP response.
@@ -35,4 +36,4 @@ class RestInputValidationError(InputValidationError):
     pass
 
 class RestFeatureNotAvailable(FeatureNotAvailable):
-    pass
+    pass

aiida/restapi/common/utils.py

@@ -115,9 +115,8 @@ def strip_prefix(self, path):
         """
         Removes the PREFIX from an URL path. PREFIX must be defined in the
         config.py file.
-        Ex. PREFIX = "/api/v2"
-            path = "/api/v2/calculations/page/2"
-            strip_prefix(path) ==> "/calculations/page/2"
+        For example, PREFIX = "/api/v2", path = "/api/v2/calculations/page/2"
+        strip_prefix(path) ==> "/calculations/page/2"
 
         :param path: the URL path string
         :return: the same URL without the prefix
@@ -145,12 +144,15 @@ def parse_path(self, path_string, parse_pk_uuid=None):
         that this is done by the Flask routing methods.
   
         :param path_string: the path string
-        :param parse_id_uuid: if 'pk' ('uuid') expects an integer (uuid 
-        starting pattern) 
-        :return:resource_type (string)
-                page (integer)
-                id (string: uuid starting pattern, int: pk)
-                query_type (string))
+        :param parse_id_uuid: if 'pk' ('uuid') expects an integer (or a string with
+           the first characters of the uuid, as long as they uniquely define a UUID)
+        :return: a tuple (source_type, page, id, query_type) 
+            where:  
+            
+              - source_type (string)
+              - page (integer)
+              - id (string: uuid starting pattern, int: pk)
+              - query_type (string))
         """
 
         ## Initialization
@@ -334,11 +336,9 @@ def paginate(self, page, perpage, total_count):
     def build_headers(self, rel_pages=None, url=None, total_count=None):
         """
         Construct the header dictionary for an HTTP response. It includes
-        related
-         pages, total count of results (before pagination).
+        related pages, total count of results (before pagination).
         :param rel_pages: a dictionary defining related pages (first, prev,
-        next,
-        last)
+        next, last)
         :param url: (string) the full url, i.e. the url that the client uses to
         get Rest resources
         :return:
@@ -413,11 +413,11 @@ def make_rel_url(rel, page):
 
     def build_response(self, status=200, headers=None, data=None):
         """
-
         :param status: status of the response, e.g. 200=OK, 400=bad request
-        :param headers: dictionary for additional header k,v pairs,
-        e.g. X-total-count=<number of rows resulting from query>
+        :param headers: dictionary for additional header k,v pairs, e.g. 
+           X-total-count=<number of rows resulting from query>
         :param data: a dictionary with the data returned by the Resource
+
         :return: a Flask response object
         """
 
@@ -493,8 +493,7 @@ def build_translator_parameters(self, field_list):
         elaborates them in order to provide translator-compliant instructions
 
         :param field_list: a (nested) list of elements resulting from parsing
-        the
-        query_string
+          the query_string
         :return: the filters in the
         """
 

aiida/restapi/run_api.py

@@ -23,23 +23,21 @@ def run_api(App, Api, *args, **kwargs):
     Takes a flask.Flask instance and runs it. Parses
     command-line flags to configure the app.
 
-    App: Class inheriting from Flask app class  
-    Api = flask_restful API class to be used to wrap the app
-
-    *args: required by argparse
-
-    *kwargs:
-    List of valid parameters:
-    prog_name: name of the command before arguments are parsed. Useful when
-    api is embedded in a command, such as verdi restapi
-    default_host: self-explainatory
-    default_port: self-explainatory
-    default_config_dir = directory containing the config.py file used to
-    configure the RESTapi
-    parse_aiida_profile= if True, parses an option to specify the AiiDA
-    profile
-    All other passed parameters are ignored.
+    :App: Class inheriting from Flask app class  
+    :Api: flask_restful API class to be used to wrap the app
+    :args: required by argparse
+    :kwargs: List of valid parameters
+
+      - :prog_name: name of the command before arguments are parsed. Useful when
+          api is embedded in a command, such as verdi restapi
+      - default_host: self-explanatory
+      - default_port: self-explanatory
+      - default_config_dir = directory containing the config.py file used to
+      - configure the RESTapi
+      - parse_aiida_profile= if True, parses an option to specify the AiiDA
+          profile
 
+    All other passed parameters are ignored.
     """
 
     import aiida  # Mainly needed to locate the correct aiida path

aiida/restapi/translator/base.py

@@ -252,13 +252,10 @@ def set_filters(self, filters={}):
         Add filters in query_help.
 
         :param filters: it is a dictionary where keys are the tag names
-         given in the path in query_help and their values are the dictionary
-         of filters want to add for that tag name. Format for the Filters
-         dictionary:
-         filters = {
-                    "tag1" : {k1:v1, k2:v2},
-                    "tag2" : {k1:v1, k2:v2},
-                  }
+          given in the path in query_help and their values are the dictionary
+          of filters want to add for that tag name. Format for the Filters
+          dictionary:
+          filters = { "tag1" : {k1:v1, k2:v2}, "tag2" : {k1:v1, k2:v2}, }
         :return: query_help dict including filters if any.
         """
         if isinstance(filters, dict):
@@ -360,7 +357,7 @@ def set_query(self, filters=None, orders=None, projections=None, id=None):
         :param filters: dictionary with the filters
         :param orders: dictionary with the order for each tag
         :param orders: dictionary with the projections
-        :param id (integer): id of a specific node
+        :param id: id of a specific node
         """
 
         tagged_filters = {}
@@ -482,7 +479,7 @@ def get_results(self):
         Returns either list of nodes or details of single node from database
 
         :return: either list of nodes or details of single node
-        from database
+          from database
         """
 
         ## Check whether the querybuilder object has been initialized

aiida/restapi/translator/node.py

@@ -142,9 +142,8 @@ def set_query(self, filters=None, orders=None, projections=None,
         :param filters: dictionary with the filters
         :param orders: dictionary with the order for each tag
         :param projections: dictionary with the projection. It is discarded
-        if query_type=='attributes'/'extras'
-        :param query_type: (string) specify the result or the content (
-        "attr")
+          if query_type=='attributes'/'extras'
+        :param query_type: (string) specify the result or the content ( "attr")
         :param id: (integer) id of a specific node
         """
 
@@ -465,7 +464,7 @@ def get_results(self):
         Returns either a list of nodes or details of single node from database
 
         :return: either a list of nodes or the details of single node
-        from the database
+          from the database
         """
         if self._content_type is not None:
             return self._get_content()
@@ -606,4 +605,4 @@ def get_node_shape(ntype):
                 })
                 nodeCount += 1
 
-        return {"nodes": nodes, "edges": edges}
+        return {"nodes": nodes, "edges": edges}

docs/requirements_for_rtd.txt

@@ -1,5 +1,12 @@
+Flask-Cache==0.13.1
+Flask-Cors==3.0.1
+Flask-HTTPAuth==3.2.0
+Flask-RESTful==0.3.6
+Flask-SQLAlchemy==2.1
+Flask==0.10.1
 Jinja2==2.9.5
 MarkupSafe==0.23
+Pattern==2.6
 Pygments==2.2.0
 SQLAlchemy-Utils==0.31.2
 SQLAlchemy==1.0.12
@@ -19,8 +26,11 @@ docutils==0.13.1
 ecdsa==0.13
 enum34==1.1.6
 ete3==3.0.0b35
+flask-marshmallow==0.7.0
 future==0.16.0
 ipython<6.0
+itsdangerous==0.24
+marshmallow-sqlalchemy==0.10.0
 meld3==1.0.0
 numpy==1.12.0
 paramiko==2.4.0
@@ -31,7 +41,9 @@ plumpy==0.7.11
 portalocker==1.1.0
 psutil==5.4.0
 pycrypto==2.6.1
+pyparsing==2.1.10
 python-dateutil==2.6.0
+python-memcached==1.58
 python-mimeparse==0.1.4
 pytz==2014.10
 pyyaml
@@ -40,6 +52,7 @@ scipy<1.0.0
 setuptools==36.6.0
 six==1.11.0
 sphinx-rtd-theme==0.2.5b2
+sqlalchemy-migrate==0.10.0
 tabulate==0.7.5
 tzlocal==1.3
 ujson==1.35

docs/source/module_guide/index.rst

@@ -17,7 +17,8 @@ Modules (API documentation)
    ../parsers/dev
    ../querying/querybuilder/dev
    ../work/dev
+   ../restapi/dev
    ../import_export/dbimporters/dev
    ../import_export/dbexporters/dev
    ../testing/dev
-   ../tools/dev
+   ../tools/dev

docs/source/restapi/dev.rst

@@ -0,0 +1,48 @@
+REST API 
+======== 
+
+.. toctree::
+   :maxdepth: 2
+
+This section describes the different classes related to workflows, workfunctions and WorkChains.
+
+
+.. automodule:: aiida.restapi.api
+   :members:
+
+.. automodule:: aiida.restapi.resources
+   :members:
+
+.. automodule:: aiida.restapi.run_api
+   :members:
+
+.. automodule:: aiida.restapi.common.exceptions
+   :members:
+
+.. automodule:: aiida.restapi.common.utils
+   :members:
+
+.. automodule:: aiida.restapi.translator.base
+   :members:
+
+.. automodule:: aiida.restapi.translator.calculation
+   :members:
+
+.. automodule:: aiida.restapi.translator.code
+   :members:
+
+.. automodule:: aiida.restapi.translator.computer
+   :members:
+
+.. automodule:: aiida.restapi.translator.data
+   :members:
+
+.. automodule:: aiida.restapi.translator.group
+   :members:
+
+.. automodule:: aiida.restapi.translator.node
+   :members:
+
+.. automodule:: aiida.restapi.translator.user
+   :members:
+

docs/update_req_for_rtd.py

@@ -26,7 +26,8 @@ def update_req_for_rtd(pre_commit):
 
     import setup_requirements
 
-    req_for_rtd_lines = list(setup_requirements.extras_require['docs'])
+    req_for_rtd_lines = list(setup_requirements.extras_require['docs'] +
+                             setup_requirements.extras_require['REST'])
 
     required_packages = list(setup_requirements.install_requires)
     for package in required_packages: