diff options
author | Stephen Finucane <stephen@that.guru> | 2017-03-22 23:17:16 +0000 |
---|---|---|
committer | Stephen Finucane <stephen@that.guru> | 2017-04-18 22:08:32 +0100 |
commit | 06378101d9cfc0d4aec78980ae4c7eaf66a187ab (patch) | |
tree | e9b77c12c64ad0cfb6275eec72f3c54ecde46cf0 /docs/usage/rest.rst | |
parent | ea9514e09bc7608c5a9c9d16a0c2794661aaab2f (diff) | |
download | patchwork-06378101d9cfc0d4aec78980ae4c7eaf66a187ab.tar patchwork-06378101d9cfc0d4aec78980ae4c7eaf66a187ab.tar.gz |
docs: Covert usage guide
Signed-off-by: Stephen Finucane <stephen@that.guru>
Diffstat (limited to 'docs/usage/rest.rst')
-rw-r--r-- | docs/usage/rest.rst | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/docs/usage/rest.rst b/docs/usage/rest.rst new file mode 100644 index 0000000..8d6e036 --- /dev/null +++ b/docs/usage/rest.rst @@ -0,0 +1,63 @@ +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 +------------- + +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. + +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 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`: + +.. 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/ |