diff options
| -rw-r--r-- | docs/api/rest.rst | 194 | ||||
| -rw-r--r-- | docs/api/xmlrpc.rst (renamed from docs/development/xmlrpc.rst) | 51 | ||||
| -rw-r--r-- | docs/development/api.rst | 10 | ||||
| -rw-r--r-- | docs/development/rest.rst | 67 | ||||
| -rw-r--r-- | docs/index.rst | 17 | ||||
| -rw-r--r-- | docs/usage/clients.rst | 47 | ||||
| -rw-r--r-- | docs/usage/rest.rst | 38 | ||||
| -rw-r--r-- | docs/usage/xmlrpc.rst | 51 |
8 files changed, 294 insertions, 181 deletions
diff --git a/docs/api/rest.rst b/docs/api/rest.rst new file mode 100644 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 index 4b2651f..374df96 100644 --- 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 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 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 27e55ac..29f2c9d 100644 --- 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 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 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 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/ |