@@ -17,15 +17,17 @@ exposed by the API, refer to the auto-generated OpenAPI documentation at::
1717
1818where `patchwork.example.com ` refers to the URL of your Patchwork instance.
1919
20- .. versionchanged :: 4.0
20+ .. version-changed :: 4.0
2121
2222 The OpenAPI schema is now auto-generated at runtime and served at
2323 `/api/docs `. Static schema files are no longer shipped.
2424
25- .. versionchanged :: 4.0
25+ .. version-removed :: 4.0
2626
27- The XML-RPC API has been removed. Use the REST API with clients like
28- :program: `git-pw ` instead.
27+ The XML-RPC API has been removed. Use the REST API with clients like git-pw __
28+ instead.
29+
30+ __ https://github.com/getpatchwork/git-pw
2931
3032Getting Started
3133---------------
@@ -35,23 +37,25 @@ auto-generated documentation at `/api/docs`.
3537
3638REST APIs run over plain HTTP(S), thus, the API can be interfaced using
3739applications or libraries that support this widespread protocol. One such
38- application is `curl `_, which can be used to both retrieve and send information
39- to the REST API. For example, to get the version of the REST API for a
40- Patchwork instance hosted at `patchwork.example.com `, run:
41-
42- .. code-block :: shell
43-
44- $ curl -s ' https://patchwork.example.com/api/1.4/' | python -m json.tool
45- {
46- " bundles" : " https://patchwork.example.com/api/1.4/bundles/" ,
47- " covers" : " https://patchwork.example.com/api/1.4/covers/" ,
48- " events" : " https://patchwork.example.com/api/1.4/events/" ,
49- " patches" : " https://patchwork.example.com/api/1.4/patches/" ,
50- " people" : " https://patchwork.example.com/api/1.4/people/" ,
51- " projects" : " https://patchwork.example.com/api/1.4/projects/" ,
52- " series" : " https://patchwork.example.com/api/1.4/series/" ,
53- " users" : " https://patchwork.example.com/api/1.4/users/"
54- }
40+ application is curl __, which can be used to both retrieve and send information
41+ to the REST API. For example, to get the version of the REST API for a Patchwork
42+ instance hosted at `patchwork.example.com `, run:
43+
44+ __ https://curl.haxx.se/
45+
46+ .. code-block :: console
47+
48+ $ curl -sL https://patchwork.example.com/api/ | jq
49+ {
50+ "bundles": "https://patchwork.example.com/api/1.4/bundles/",
51+ "covers": "https://patchwork.example.com/api/1.4/covers/",
52+ "events": "https://patchwork.example.com/api/1.4/events/",
53+ "patches": "https://patchwork.example.com/api/1.4/patches/",
54+ "people": "https://patchwork.example.com/api/1.4/people/",
55+ "projects": "https://patchwork.example.com/api/1.4/projects/",
56+ "series": "https://patchwork.example.com/api/1.4/series/",
57+ "users": "https://patchwork.example.com/api/1.4/users/"
58+ }
5559
5660 Tools like `curl ` and libraries like `requests ` can be used to build anything
5761from small utilities to full-fledged clients targeting the REST API. For an
@@ -104,33 +108,35 @@ Parameters
104108
105109For `GET ` requests, parameters should be passed as HTTP query string parameters:
106110
107- .. code-block :: shell
111+ .. code-block :: console
108112
109- $ curl ' https://patchwork.example.com/api/patches?state=under-review'
113+ $ curl 'https://patchwork.example.com/api/patches?state=under-review'
110114
111115 For `POST ` and `PATCH ` requests, parameters should be encoded as JSON with
112116a `Content-Type ` of `application/json `:
113117
114- .. code-block :: shell
118+ .. code-block :: console
115119
116- $ curl -X PATCH \
117- --header " Content-Type: application/json" \
118- --data ' {"state":"under-review"}' \
119- ' https://patchwork.example.com/api/patches/123/ '
120+ $ curl -X PATCH \
121+ --header "Content-Type: application/json" \
122+ --data '{"state":"under-review"}' \
123+ https://patchwork.example.com/api/patches/123
120124
121125 Authentication
122126--------------
123127
124128Patchwork supports authentication using bearer token authentication. To
125- authenticate, first generate a token from your user profile page, then::
129+ authenticate, first generate a token from your user profile page, then:
130+
131+ .. code-block :: console
132+
133+ $ curl -H "Authorization: Bearer $token" https://patchwork.example.com/api
126134
127- $ curl -H "Authorization: Bearer ${token}" \
128- 'https://patchwork.example.com/api/'
135+ The legacy `Token ` scheme is also accepted for backward compatibility:
129136
130- The legacy ` Token ` scheme is also accepted for backward compatibility::
137+ .. code-block :: console
131138
132- $ curl -H "Authorization: Token ${token}" \
133- 'https://patchwork.example.com/api/'
139+ $ curl -H "Authorization: Token $token" https://patchwork.example.com/api
134140
135141 Not all resources require authentication. Those that do will return
136142`401 (Unauthorized) ` if authentication is not provided.
@@ -144,12 +150,9 @@ can change page using the `?page` parameter and set custom page sizes up to
144150
145151.. code-block :: shell
146152
147- $ curl ' https://patchwork.example.com/api/patches?page=2&per_page=100'
153+ $ curl ' https://patchwork.example.com/api/patches?page=2&per_page=100'
148154
149155 The `Link ` header includes pagination information::
150156
151157 Link: <https://patchwork.example.com/api/patches?page=3&per_page=100>; rel="next",
152158 <https://patchwork.example.com/api/patches?page=50&per_page=100>; rel="last"
153-
154-
155- .. _curl : https://curl.haxx.se/
0 commit comments