docs: Split API docs into their own section

Third time lucky. There are two changes:

- Add a new 'clients' section to the usage doc, allowing us to remove a
  lot of the API nitty gritty stuff from the users guide. This makes
  more sense as users don't really care what API method they're using -
  only what application).

- Change the API docs from the developers guide into a quick start
  section, allowing us to greatly expand the REST API docs to include
  information on pagination, authentication, etc.

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/api/rest.rst b/docs/api/rest.rst
new file mode 100644 (file)
index 0000000..75e31f6
--- /dev/null
+++ b/docs/api/rest.rst
@@ -0,0 +1,194 @@
+The REST API
+============
+
+Patchwork provides a REST API. This API can be used to retrieve and modify
+information about patches, projects and more.
+
+This guide provides an overview of how one can interact with the REST API. For
+detailed information on type and response format of the various resources
+exposed by the API, refer to the web browsable API. This can be found at:
+
+    https://patchwork.example.com/api/1.0/
+
+where `patchwork.example.com` refers to the URL of your Patchwork instance.
+
+.. important::
+
+   The REST API can be enabled/disabled by the administrator: it may not be
+   available in every instance. Refer to ``/about`` on your given instance for
+   the status of the API, e.g.
+
+       https://patchwork.ozlabs.org/about
+
+.. versionadded:: 2.0
+
+   The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork
+   versions should instead refer to :doc:`XML-RPC API <xmlrpc>` documentation.
+
+Getting Started
+---------------
+
+The easiest way to start experimenting with the API is to use the web browsable
+API, as described above.
+
+REST APIs run over plain HTTP(S), thus, the API can be interfaced using
+applications or libraries that support this widespread protocol. One such
+application is `curl`_, which can be used to both retrieve and send information
+to the REST API. For example, to get the version of the REST API for a
+Patchwork instance hosted at `patchwork.example.com`, run:
+
+.. code-block:: shell
+
+    $ curl -s 'https://patchwork.example.com/api/1.0/' | python -m json.tool
+    {
+        "bundles": "https://patchwork.example.com/api/1.0/bundles/",
+        "covers": "https://patchwork.example.com/api/1.0/covers/",
+        "events": "https://patchwork.example.com/api/1.0/events/",
+        "patches": "https://patchwork.example.com/api/1.0/patches/",
+        "people": "https://patchwork.example.com/api/1.0/people/",
+        "projects": "https://patchwork.example.com/api/1.0/projects/",
+        "series": "https://patchwork.example.com/api/1.0/series/",
+        "users": "https://patchwork.example.com/api/1.0/users/"
+    }
+
+
+In addition, a huge variety of libraries are available for interacting with and
+parsing the output of REST APIs. The `requests`_ library is wide-spread and
+well-supported. To repeat the above example using `requests`:, run
+
+.. code-block:: pycon
+
+    $ python
+    >>> import json
+    >>> import requests
+    >>> r = requests.get('https://patchwork.example.com/api/1.0/')
+    >>> print(json.dumps(r.json(), indent=2))
+    {
+        "bundles": "https://patchwork.example.com/api/1.0/bundles/",
+        "covers": "https://patchwork.example.com/api/1.0/covers/",
+        "events": "https://patchwork.example.com/api/1.0/events/",
+        "patches": "https://patchwork.example.com/api/1.0/patches/",
+        "people": "https://patchwork.example.com/api/1.0/people/",
+        "projects": "https://patchwork.example.com/api/1.0/projects/",
+        "series": "https://patchwork.example.com/api/1.0/series/",
+        "users": "https://patchwork.example.com/api/1.0/users/"
+    }
+
+Tools like `curl` and libraries like `requests` can be used to build anything
+from small utilities to full-fledged clients targeting the REST API. For an
+overview of existing API clients, refer to :doc:`../usage/clients`.
+
+.. tip::
+
+    While you can do a lot with existing installations, it's possible that you
+    might not have access to all resources or may not wish to modify any
+    existing resources. In this case, it might be better to :doc:`deploy your
+    own instance of Patchwork locally <../development/installation>` and
+    experiment with that instead.
+
+Schema
+------
+
+Responses are returned as JSON. Blank fields are returned as ``null``, rather
+than being omitted. Timestamps use the ISO 8601 format::
+
+    YYYY-MM-DDTHH:MM:SSZ
+
+Requests should use either query parameters or form-data, depending on the
+method. Further information is provided `below <rest_parameters>`__.
+
+Summary Representations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Some resources are particularly large or expensive to compute. When listing
+these resources, a summary representation is returned that omits certain
+fields.  To get all fields, fetch the detailed representation. For example,
+listing patches will return summary representations for each patch:
+
+.. code-block:: http
+
+    GET /patches HTTP/1.1
+
+Detailed Representations
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When fetching an individual resource, all fields will be returned. For example,
+fetching a patch with an ID of ``123`` will return all available fields for
+that particular resource:
+
+.. code-block:: http
+
+    GET /patches/123 HTTP/1.1
+
+.. _rest_parameters:
+
+Parameters
+----------
+
+Most API methods take optional parameters. For ``GET`` requests, these
+parameters are mostly used for filtering and should be passed as a HTTP query
+string parameters:
+
+.. code-block:: shell
+
+    $ curl 'https://patchwork.example.com/api/patches?state=under-review'
+
+For all other types of requests, including ``POST`` and ``PATCH``, these
+parameters should be passed as form-encoded data:
+
+.. code-block:: shell
+
+    $ curl -X POST -F 'state=under-review' \
+      'https://patchwork.example.com/api/patches/123'
+
+Authentication
+--------------
+
+Patchwork only supports basic authentication:
+
+.. code-block:: shell
+
+    $ curl -u username:password 'https://patchwork.example.com/api/'
+
+Not all resources require authentication. Those that do will return ``404 Not
+Found`` if authentication is not provided to avoid leaking information.
+
+Pagination
+----------
+
+Requests that return multiple items will be paginated by 30 items by default,
+though this can vary from instance to instance. You can change page using the
+``?page`` parameter. You can also set custom page sizes up to 100 on most
+endpoints using the ``?per_page`` parameter.
+
+.. code-block:: shell
+
+    $ curl 'https://patchwork.example.com/api/patches?page=2&per_page=100'
+
+Link Header
+~~~~~~~~~~~
+
+The `Link header`_ includes pagination information::
+
+    Link: <https://patchwork.example.com/api/patches?page=3&per_page=100>; rel="next",
+      <https://patchwork.example.com/api/patches?page=50&per_page=100>; rel="last"
+
+The possible ``rel`` values are:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - ``next``
+     - The link relation for the immediate next page of results.
+   * - ``last``
+     - The link relation for the last page of results.
+   * - ``first``
+     - The link relation for the first page of results.
+   * - ``prev``
+     - The link relation for the immediate previous page of results.
+
+.. _curl: https://curl.haxx.se/
+.. _requests: http://docs.python-requests.org/en/master/
+.. _Link header: https://tools.ietf.org/html/rfc5988

diff --git a/docs/development/xmlrpc.rst b/docs/api/xmlrpc.rst
similarity index 59%
rename from docs/development/xmlrpc.rst
rename to docs/api/xmlrpc.rst
index 4b2651f1cad4370d0b162c73f8a38fe49f3d4c82..374df964861bc0c9b03c12125cd9d27fb8b0e82e 100644 (file)
--- a/docs/development/xmlrpc.rst
+++ b/docs/api/xmlrpc.rst
@@ -4,36 +4,32 @@ The XML-RPC API
 Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
 and modify information about patches, projects and more.
 
-This guide covers development information for the Patchwork XML-RPC API. For
-information on using the REST API, refer to `rest`. For information on general
-usage of the XML-RPC API, refer to :doc:`../usage/xmlrpc`.
+.. important::
 
-Documentation
--------------
+   The XML-RPC API can be enabled/disabled by the administrator: it may not be
+   available in every instance. Refer to ``/about`` on your given instance for
+   the status of the API, e.g.
 
-Patchwork provides automatically generated documentation for the XML-RPC API.
-You can find this at the following URL:
+       https://patchwork.ozlabs.org/about
 
-    http://patchwork.example.com/xmlrpc/
+   Alternatively, simply attempt to make a request to the API.
 
-where `patchwork.example.com` refers to the URL of your Patchwork instance.
-
-.. versionchanged:: 1.1
+.. deprecated:: 2.0
 
-   Automatic documentation generation for the Patchwork API was introduced in
-   Patchwork v1.1. Prior versions of Patchwork do not offer this functionality.
+    The XML-RPC API is a legacy API and has been deprecated in favour of the
+    :doc:`REST API <rest>`. It will be removed in Patchwork 3.0.
 
-Interacting with the API
-------------------------
+Getting Started
+---------------
 
 The Patchwork XML-RPC API provides a number of "methods". Some methods require
 authentication (via HTTP Basic Auth) while others do not. Authentication uses
 your Patchwork account and the on-server documentation will indicate where it
 is necessary. We will only cover the unauthenticated method here for brevity -
-consult the `xmlrpclib`__ documentation for more detailed examples:
+consult the `xmlrpclib`_ documentation for more detailed examples:
 
 To interact with the Patchwork XML-RPC API, a XML-RPC library should be used.
-Python provides such a library - `xmlrpclib` - in its standard library. For
+Python provides such a library - `xmlrpclib`_ - in its standard library. For
 example, to get the version of the XML-RPC API for a Patchwork instance hosted
 at `patchwork.example.com`, run:
 
@@ -45,9 +41,24 @@ at `patchwork.example.com`, run:
     >>> rpc.pw_rpc_version()
     1.1
 
-Once connected, the `rpc` object will be populated with a list of available
+Once connected, the ``rpc`` object will be populated with a list of available
 functions (or procedures, in RPC terminology). In the above example, we used
-the `pw_rpc_version` method, however, it should be possible to use all the
+the ``pw_rpc_version`` method, however, it should be possible to use all the
 methods listed in the server documentation.
 
-__ https://docs.python.org/2/library/xmlrpclib.html
+Further Information
+-------------------
+
+Patchwork provides automatically generated documentation for the XML-RPC API.
+You can find this at the following URL:
+
+    https://patchwork.example.com/xmlrpc/
+
+where `patchwork.example.com` refers to the URL of your Patchwork instance.
+
+.. versionchanged:: 1.1
+
+   Automatic documentation generation for the Patchwork API was introduced in
+   Patchwork v1.1. Prior versions of Patchwork do not offer this functionality.
+
+.. _xmlrpclib: https://docs.python.org/2/library/xmlrpclib.html

diff --git a/docs/development/api.rst b/docs/development/api.rst
new file mode 100644 (file)
index 0000000..3cfefdb
--- /dev/null
+++ b/docs/development/api.rst
@@ -0,0 +1,10 @@
+Using the APIs
+==============
+
+Patchwork provides two APIs: the legacy :doc:`XML-RPC API <../api/xmlrpc>` and
+the :doc:`REST API <../api/rest>`. You can use these APIs to interact with
+Patchwork programmatically and to develop your own clients.
+
+For quick usage examples of the APIs, refer to the :ref:`documentation
+<api-docs>`. For examples of existing clients, refer to
+:doc:`../usage/clients`.

diff --git a/docs/development/rest.rst b/docs/development/rest.rst
deleted file mode 100644 (file)
index efab9f4..0000000
--- a/docs/development/rest.rst
+++ /dev/null
@@ -1,67 +0,0 @@
-The REST API
-============
-
-Patchwork provides a REST API. This API can be used to retrieve and modify
-information about patches, projects and more.
-
-This guide covers development information for the Patchwork REST API. For
-information on using the REST API, refer to `rest`. For information on general
-usage of the REST API, refer to :doc:`../usage/rest`.
-
-.. versionadded:: 2.0
-
-   The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork
-   versions should instead refer to :doc:`xmlrpc`.
-
-Documentation
--------------
-
-Patchwork provides automatically generated documentation for the REST API.
-You can find this at the following URL:
-
-    http://patchwork.example.com/api/
-
-where `patchwork.example.com` refers to the URL of your Patchwork instance.
-
-Interacting with the API
-------------------------
-
-REST APIs run over plain HTTP(S), thus, the API can be interfaced using
-applications or libraries that support this widespread protocol. One such
-application is `curl`__, which can be used to both retrieve and send
-information to the REST API. For example, to get the version of the REST API
-for a Patchwork instance hosted at `patchwork.example.com`, run:
-
-.. code-block:: shell
-
-    $ curl -s http://localhost:8000/api/1.0/ | python -m json.tool
-    {
-        "patches": "http://localhost:8000/api/1.0/patches/",
-        "people": "http://localhost:8000/api/1.0/people/",
-        "projects": "http://localhost:8000/api/1.0/projects/",
-        "users": "http://localhost:8000/api/1.0/users/"
-    }
-
-In addition, a huge variety of libraries are available for interacting with and
-parsing the output of REST APIs. The `requests`__ library is wide-spread and
-well-supported. To repeat the above example using `requests`:
-
-.. code-block:: pycon
-
-    $ python
-    >>> import json
-    >>> import requests
-    >>> r = requests.get('http://patchwork.example.com/api/1.0/')
-    >>> print(json.dumps(r.json(), indent=2))
-    {
-          "users": "http://localhost:8000/api/1.0/users/",
-          "patches": "http://localhost:8000/api/1.0/patches/",
-          "projects": "http://localhost:8000/api/1.0/projects/",
-          "people": "http://localhost:8000/api/1.0/people/"
-    }
-
-Tools like `curl` and libraries like `requests` can be used to build anything
-from small utilities to full-fledged clients targeting the REST API.
-
-__ https://curl.haxx.se/
-__ http://docs.python-requests.org/en/master/

diff --git a/docs/index.rst b/docs/index.rst
index 27e55ac87160eb7b17a73316db412527c40a89e1..29f2c9d31ad1a537f8423c37d3995a5bc5303e6e 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,8 +27,7 @@ of community projects.
    usage/design
    usage/delegation
    usage/headers
-   usage/rest
-   usage/xmlrpc
+   usage/clients
 
 .. _deployment-docs:
 
@@ -39,7 +38,7 @@ of community projects.
    deployment/installation
    deployment/upgrading
 
-.. development-docs:
+.. _development-docs:
 
 .. toctree::
    :maxdepth: 2
@@ -48,8 +47,16 @@ of community projects.
    development/contributing
    development/installation
    development/releasing
-   development/rest
-   development/xmlrpc
+   development/api
+
+.. _api-docs:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Documentation
+
+   api/rest
+   api/xmlrpc
 
 .. _release-note-docs:
 

diff --git a/docs/usage/clients.rst b/docs/usage/clients.rst
new file mode 100644 (file)
index 0000000..a131fc8
--- /dev/null
+++ b/docs/usage/clients.rst
@@ -0,0 +1,47 @@
+Clients
+=======
+
+A number of clients are available for interacting with Patchwork's various
+APIs.
+
+pwclient
+--------
+
+The `pwclient` application, provided with Patchwork, can be used to interact
+with Patchwork from the command line. Functionality provided by `pwclient`
+includes:
+
+- Listing patches, projects, and checks
+- Downloading and applying patches to a local code base
+- Modifying the status of patches
+- Creating new checks
+
+`pwclient` can be downloaded from the `Ozlabs Patchwork instance`__, or at the
+following path for most other Patchwork instances:
+
+    http://patchwork.example.com/pwclient/
+
+where `patchwork.example.com` corresponds to the URL a Patchwork instance is
+hosted at.
+
+Once downloaded, view information about all the operations supported by
+`pwclient`, run:
+
+.. code-block:: shell
+
+    $ pwclient --help
+
+__ https://patchwork.ozlabs.org/pwclient/
+
+git-pw
+------
+
+The `git-pw` application can be used to integrate Git with Patchwork. The
+`git-pw` application relies on the REST API and can be used to interact to
+list, download and apply series, bundles and individual patches.
+
+More information on `git-pw`, including installation and usage instructions,
+can be found in the `documentation`__ and the `GitHub repo`__.
+
+__ https://git-pw.readthedocs.io/
+__ https://github.com/getpatchwork/git-pw

diff --git a/docs/usage/rest.rst b/docs/usage/rest.rst
deleted file mode 100644 (file)
index 33808bc..0000000
--- a/docs/usage/rest.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-The REST API
-============
-
-.. note::
-
-   This guide covers usage information for the Patchwork REST API. For
-   information on using the XML-RPC API, refer to :doc:`xmlrpc`. For
-   information on developing custom applications or clients for this API, refer
-   to the :doc:`../development/rest`.
-
-Patchwork provides a REST API. This API can be used to retrieve and modify
-information about patches, projects and more.
-
-.. important::
-
-   The REST API can be enabled/disabled by the administrator: it may not be
-   available in every instance. Refer to ``/about`` on your given instance for
-   the status of the API, e.g.
-
-       https://patchwork.ozlabs.org/about
-
-.. versionadded:: 2.0
-
-   The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork
-   versions should instead refer to :doc:`xmlrpc`.
-
-git-pw
-------
-
-The `git-pw` application can be used to integrate Git with Patchwork. The
-`git-pw` application relies on the REST API and can be used to interact to
-list, download and apply series, bundles and individual patches.
-
-More information on `git-pw`, including installation and usage instructions,
-can be found in the `documentation`__ and the `GitHub repo`__.
-
-__ https://git-pw.readthedocs.io/
-__ https://github.com/getpatchwork/git-pw

diff --git a/docs/usage/xmlrpc.rst b/docs/usage/xmlrpc.rst
deleted file mode 100644 (file)
index 1bebcc8..0000000
--- a/docs/usage/xmlrpc.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-The XML-RPC API
-===============
-
-.. note::
-
-   This guide covers usage information for the Patchwork XML-RPC API.  For
-   information on using the REST API, refer to :doc:`rest`. For information on
-   developing custom applications or clients for this API, refer to the
-   :doc:`../development/xmlrpc`.
-
-Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
-and modify information about patches, projects and more.
-
-.. important::
-
-   The XML-RPC API can be enabled/disabled by the administrator: it may not be
-   available in every instance. Refer to ``/about`` on your given instance for
-   the status of the API, e.g.
-
-       https://patchwork.ozlabs.org/about
-
-   This URL is only supported on Patchwork 2.0+.
-
-pwclient
---------
-
-The `pwclient` application, provided with Patchwork, can be used to interact
-with Patchwork from the command line. Functionality provided by `pwclient`
-includes:
-
-* Listing patches, projects, and checks
-* Downloading and applying patches to a local code base
-* Modifying the status of patches
-* Creating new checks
-
-pwclient can be downloaded from the `Ozlabs Patchwork instance`__, or at the
-following path for other Patchwork instances:
-
-    http://patchwork.example.com/pwclient/
-
-where `patchwork.example.com` corresponds to the URL a Patchwork instance is
-hosted at.
-
-Once downloaded, to view information about all the operations supported by
-`pwclient`, run:
-
-.. code-block:: shell
-
-    $ pwclient --help
-
-__ https://patchwork.ozlabs.org/pwclient/