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
|
# 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 the [XML-RPC API
documentation][doc-xmlrpc].
## Patchwork REST API 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`][ref-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:
$ 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`][ref-requests] library is
wide-spread and well-supported. To repeat the above example using `requests`:
$ 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.
[doc-xmlrpc]: xmlrpc.md
[ref-curl]: https://curl.haxx.se/
[ref-requests]: http://docs.python-requests.org/en/master/
|