diff options
| -rw-r--r-- | docs/development/rest.rst | 67 | ||||
| -rw-r--r-- | docs/development/xmlrpc.rst | 7 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/usage/rest.rst | 71 | ||||
| -rw-r--r-- | docs/usage/xmlrpc.rst | 11 |
5 files changed, 100 insertions, 57 deletions
diff --git a/docs/development/rest.rst b/docs/development/rest.rst new file mode 100644 index 0000000..efab9f4 --- /dev/null +++ b/docs/development/rest.rst @@ -0,0 +1,67 @@ +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/development/xmlrpc.rst b/docs/development/xmlrpc.rst index 9842c78..4b2651f 100644 --- a/docs/development/xmlrpc.rst +++ b/docs/development/xmlrpc.rst @@ -8,11 +8,6 @@ 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`. -.. note:: - - The XML-RPC API can be enabled/disabled by the administrator: it may not be - available in every instance. - Documentation ------------- @@ -23,7 +18,7 @@ You can find this at the following URL: where `patchwork.example.com` refers to the URL of your Patchwork instance. -.. note:: +.. 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. diff --git a/docs/index.rst b/docs/index.rst index 6a61bad..27e55ac 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,6 +48,7 @@ of community projects. development/contributing development/installation development/releasing + development/rest development/xmlrpc .. _release-note-docs: diff --git a/docs/usage/rest.rst b/docs/usage/rest.rst index 8d6e036..33808bc 100644 --- a/docs/usage/rest.rst +++ b/docs/usage/rest.rst @@ -1,63 +1,38 @@ The REST API ============ -Patchwork provides a REST API. This API can be used to retrieve and modify -information about patches, projects and more. - .. note:: - The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork - versions should instead refer to :doc:`xmlrpc`. - -Documentation -------------- + 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 automatically generated documentation for the RESET 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. +Patchwork provides a REST API. This API can be used to retrieve and modify +information about patches, projects and more. -Interacting with the API ------------------------- +.. important:: -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: + 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. -.. code-block:: shell + https://patchwork.ozlabs.org/about - $ 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/" - } +.. versionadded:: 2.0 -In addition, a huge variety of libraries are avaiable 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`: + The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork + versions should instead refer to :doc:`xmlrpc`. -.. code-block:: pycon +git-pw +------ - $ 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/" - } +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. -Tools like `curl` and libraries like `requests` can be used to build anything -from small utilities to full-fledged clients targeting the REST API. +More information on `git-pw`, including installation and usage instructions, +can be found in the `documentation`__ and the `GitHub repo`__. -__ https://curl.haxx.se/ -__ http://docs.python-requests.org/en/master/ +__ https://git-pw.readthedocs.io/ +__ https://github.com/getpatchwork/git-pw diff --git a/docs/usage/xmlrpc.rst b/docs/usage/xmlrpc.rst index 644e8e2..1bebcc8 100644 --- a/docs/usage/xmlrpc.rst +++ b/docs/usage/xmlrpc.rst @@ -6,15 +6,20 @@ The XML-RPC API 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 - `../development/xmlrpc`. + :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. -.. note:: +.. important:: The XML-RPC API can be enabled/disabled by the administrator: it may not be - available in every instance. + 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 -------- |