--- /dev/null
+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/
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
-------------
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.
development/contributing
development/installation
development/releasing
+ development/rest
development/xmlrpc
.. _release-note-docs:
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
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
--------
projects / thirdparty / patchwork.git / commitdiff
