1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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/
|