Add documentation for formList endpoints

docs/authentication.rst

@@ -176,7 +176,7 @@ Where:
 
 -  ``access_token`` - access token - expires
 -  ``refresh_token`` - token to use to request a new ``access_token`` in
-   case it has expored.
+   case it has expired.
 
 Now that you have an ``access_token`` you can make API calls.
 

docs/formlist.rst

@@ -0,0 +1,147 @@
+FormList endpoints
+*************************
+
+Implements OpenRosa API |FormListAPI|
+
+.. |FormListAPI| raw:: html
+
+    <a href="https://bitbucket.org/javarosa/javarosa/wiki/FormListAPI"
+    target="_blank">here</a>
+
+GET a list of forms
+-------------------
+
+These endpoints provide a discovery mechanism for returning the set of forms available for download.
+The forms are filtered based upon the user's identity, where:
+
+- ``form_pk`` - is the identifying number for a specific form
+- ``user_name`` - username parameter allows filtering of forms to those owned by the user
+
+
+.. raw:: html
+
+    <pre class="prettyprint">
+    <b>POST</b> /formList</pre>
+
+Example
+^^^^^^^
+::
+
+    curl -X GET https://api.ona.io/formList
+
+Response:
+::
+
+<xforms>
+<xform>
+<formID>form_id</formID>
+<name>name</name>
+<version>202006121145</version>
+<hash>md5:965fad0dbad4bb708d18abe77fcfe358</hash>
+<descriptionText/>
+<downloadUrl>https://api.ona.io/user_name/forms/form_pk/form.xml</downloadUrl>
+</xform>
+<xform>
+<formID>testerform</formID>
+<name>testerform</name>
+<version>201904231241</version>
+<hash>md5:a023b3535b7b593de1e9ad075e9e21e6</hash>
+<descriptionText/>
+<downloadUrl>https://api.ona.io/user_name/forms/form_pk/form.xml</downloadUrl>
+<manifestUrl>https://api.ona.io/user_name/xformsManifest/1620</manifestUrl>
+</xform>
+</xforms>
+
+
+
+Retreive a single form
+----------------------
+
+There a multiple endpoints that implement the ability to retrieve a Single XForm; The forms are divided by the filters they support:
+
+GET /<username>/<form_pk>/formList
+
+**Pass username and form pk**
+
+Example
+^^^^^^^
+::
+
+    curl -X GET https://stage-api.ona.io/<user_name>/<form_pk>/formList
+
+Filter formlist by ``user_name`` and ``form_pk``
+
+Response:
+::
+
+<xforms>
+<xform>
+<formID>form_id</formID>
+<name>name</name>
+<version>202006121145</version>
+<hash>md5:965fad0dbad4bb708d18abe77fcfe358</hash>
+<descriptionText/>
+<downloadUrl>https://api.ona.io/user_name/forms/form_pk/form.xml</downloadUrl>
+</xform>
+</xforms>
+
+
+
+GET /enketo/<xform_pk>/formList
+
+
+**Use enketo/<xform_pk> endpoint**
+
+Example
+^^^^^^^
+
+::
+
+    curl -X GET https://stage-api.ona.io/enketo/<form_pk>/formList
+
+Filter formlist by ``user_name`` and ``form_pk``, allowing for access to formlist by annonymous users
+
+
+Response:
+::
+
+<xforms>
+<xform>
+<formID>form_id</formID>
+<name>name</name>
+<version>202006121145</version>
+<hash>md5:965fad0dbad4bb708d18abe77fcfe358</hash>
+<descriptionText/>
+<downloadUrl>https://api.ona.io/user_name/forms/form_pk/form.xml</downloadUrl>
+</xform>
+</xforms>
+
+
+
+GET /enketo-preview/<xform_pk>/formList
+
+**Use enketo-preview/<xform_pk> endpoint**
+
+Example
+^^^^^^^
+
+::
+
+    curl -X GET https://stage-api.ona.io/enketo-preview/<form_pk>/formList
+
+Filter formlist by ``user_name`` and ``form_pk``, allowing for access to formlist by users without can-submit priviledges
+
+
+Response:
+::
+
+<xforms>
+<xform>
+<formID>form_id</formID>
+<name>name</name>
+<version>202006121145</version>
+<hash>md5:965fad0dbad4bb708d18abe77fcfe358</hash>
+<descriptionText/>
+<downloadUrl>https://api.ona.io/user_name/forms/form_pk/form.xml</downloadUrl>
+</xform>
+</xforms>

docs/forms.rst

@@ -217,8 +217,7 @@ Set Form Information
 --------------------
 
 You can use ``PUT`` or ``PATCH`` http methods to update or set form data elements.
-If you are using ``PUT``, you have to provide the `uuid, description,
-downloadable, owner, public, public_data, title` fields. With ``PATCH`` you only need to provide at least one of the fields.
+If you are using ``PUT``, you have to provide the `uuid, description, downloadable, owner, public, public_data, title` fields. With ``PATCH`` you only need to provide at least one of the fields.
 
 Replacing a Form
 ----------------

docs/index.rst

@@ -36,6 +36,7 @@ Forms
    :maxdepth: 2
 
    forms
+   formlist
    media
    metadata
    notes