REST API¶
Patchwork exposes a REST API to allow other systems and scripts to interact with it. The basic service it offers is exposing a mailing-list used for sending patches and review comments as high level objects: series, revisions and patches.
- series
A collection of revisions. Series objects are created, along with an initial revision, when a set of patches are sent to a mailing-list, usually through git send-email. Series can evolve over time and gain new revisions as the work matures through reviews, testing and new iterations.
More about series and revisions can be found in Submitting patches.
- revision
- A collection of patches.
- patch
- The usual collection of changes expressed as a diff. With git, a patch also contains full commit metadata.
API Patterns¶
All the API entry points share common patterns to offer a coherent whole and limit surprises when using the API.
Lists¶
Various entry points expose lists of objects. They all follow the same structure:
{
"count": 25,
"next": "http://patchwork.example.com/api/1.0/series/?page=2",
"previous": null,
"results": [
{
"object": 0
},
{
"object": 1
},
{
},
{
"object": 19
},
]
}
Lists are paginated with 20 elements per page by default. count
is the
total number of objects while next
and previous
will hold URLs to the
next and previous pages. It’s possible to change the number of elements per
page with the perpage
GET parameter, with a limit of 100 elements per page.
API Reference¶
API Metadata¶
-
GET
/api/1.0/
¶ Metadata about the API itself.
GET /api/1.0/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "revision": 0 }
Response JSON Object: - revision (int) – API revision. This can be used to ensure the server supports a feature introduced from a specific revision. The list of API revisions and the changes introduced by each of them is documented in API Revisions.
Projects¶
A project is merely one of the projects defined for this patchwork instance.
-
GET
/api/1.0/projects/
¶ List of all projects.
GET /api/1.0/projects/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "count": 2, "next": null, "previous": null, "results": [ { "id": 2, "name": "beignet", "linkname": "beignet", "listemail": "beignet@lists.freedesktop.org", "web_url": "http://www.freedesktop.org/wiki/Software/Beignet/", "scm_url": "git://anongit.freedesktop.org/git/beignet", "webscm_url": "http://cgit.freedesktop.org/beignet/" }, { "id": 1, "name": "Cairo", "linkname": "cairo", "listemail": "cairo@cairographics.org", "web_url": "http://www.cairographics.org/", "scm_url": "git://anongit.freedesktop.org/git/cairo", "webscm_url": "http://cgit.freedesktop.org/cairo/" } ] }
-
GET
/api/1.0/projects/(string: linkname)/
¶
-
GET
/api/1.0/projects/(int: project_id)/
¶ GET /api/1.0/projects/intel-gfx/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "id": 1, "name": "intel-gfx", "linkname": "intel-gfx", "listemail": "intel-gfx@lists.freedesktop.org", "web_url": "", "scm_url": "", "webscm_url": "" }
Events¶
-
GET
/api/1.0/projects/(string: linkname)/events/
¶
-
GET
/api/1.0/projects/(int: project_id)/events/
¶ List of events for this project.
GET /api/1.0/projects/intel-gfx/events/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "count": 23, "next": "http://patchwork.example.com/api/1.0/events/?page=2", "previous": null, "results": [ { "name": "series-new-revision", "event_time": "2015-10-20T19:49:49.494183", "series": 23, "user": null, "parameters": { "revision": 2 } }, { }, { "name": "series-new-revision", "event_time": "2015-10-20T19:49:43.895382", "series": 22, "user": null, "parameters": { "revision": 1 } } ] }
Query Parameters: - since – Retrieve only events newer than a specific time. Format is
the same as
event_time
in response, an ISO 8601 date. That means that theevent_time
from the last seen event can be used in the next query with asince
parameter to only retrieve events that haven’t been seen yet.
- since – Retrieve only events newer than a specific time. Format is
the same as
Each event type has some parameters
specific to that event. At the moment,
only one event is possible:
series-new-revision: This event corresponds to patchwork receiving a new revision of a series, should it be the initial submission or subsequent updates. The difference can be made by looking at the version of the series.
This event only appears when patchwork has received the full set of mails belonging to the same series, so the revision object is guaranteed to contain all patches.
revision: The version of the new revision that has been created.
series
andrevision
can be used to retrieve the corresponding patches.
Series¶
A series object represents a lists of patches sent to the mailing-list through git send-email. It also includes all subsequent patches that are sent to address review comments, both single patch and full new series.
A series has then n
revisions, n
going from 1
to version
.
-
GET
/api/1.0/projects/(string: linkname)/series/
¶
-
GET
/api/1.0/projects/(int: project_id)/series/
¶ List of all Series belonging to a specific project. The project can be specified using either its
linkname
orid
.GET /api/1.0/projects/intel-gfx/series/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "count": 59, "next": "http://patchwork.example.com/api/1.0/projects/intel-gfx/series/?page=2", "previous": null, "results": [ { "id": 3, "project": 1, "name": "drm/i915: Unwind partial VMA rebinding after failure in set-cache-level", "n_patches": 1, "submitter": 77, "submitted": "2015-10-09T11:51:38", "last_updated": "2015-10-09T11:51:59.013345", "version": 1, "reviewer": null }, { "id": 5, "project": 1, "name": "RFC drm/i915: Stop the machine whilst capturing the GPU crash dump", "n_patches": 1, "submitter": 77, "submitted": "2015-10-09T12:21:45", "last_updated": "2015-10-09T12:21:58.657976", "version": 1, "reviewer": null, } ] }
Query Parameters: - submitter – Filter series by submitter
id
.self
can be used as a special value meaning the current logged in user. - reviewer – Filter series by reviewer
id
ornull
for no reviewer assigned. - submitted_since – Retrieve only submitted series newer than a
specified time. Format is the same as
submitted
in response, an ISO 8601 date. - updated_since – Retrieve only updated series newer than a
specified time. Format is the same as
last_updated
in response, an ISO 8601 date. - submitted_before – Retrieve only submitted series older than the
specified time. Format is the same as
submitted
in response, an ISO 8601 date. - updated_before – Retrieve only updated series older than a
specified time. Format is the same as
last_updated
in response, an ISO 8601 date.
- submitter – Filter series by submitter
-
GET
/api/1.0/series/
¶ List of all Series known to patchwork.
GET /api/1.0/series/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "count": 344, "next": "http://patchwork.example.com/api/1.0/series/?page=2", "previous": null, "results": [ { "id": 10, "project": 1, "name": "intel: New libdrm interface to create unbound wc user mappings for objects", "n_patches": 1, "submitter": 10, "submitted": "2015-01-02T11:06:40", "last_updated": "2015-10-09T07:55:18.608251", "version": 1, "reviewer": null }, { "id": 1, "project": 1, "name": "PMIC based Panel and Backlight Control", "n_patches": 4, "submitter": 1, "submitted": "2014-12-26T10:23:26", "last_updated": "2015-10-09T07:55:01.558523", "version": 1, "reviewer": null, }, ] }
-
GET
/api/1.0/series/(int: series_id)/
¶ A series (series_id). A Series object contains metadata about the series.
GET /api/1.0/series/47/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, PUT, PATCH, HEAD, OPTIONS { "id": 47, "name": "Series without cover letter", "n_patches": 2, "submitter": 21, "submitted": "2015-01-13T09:32:24", "last_updated": "2015-10-09T07:57:23.541373", "version": 1, "reviewer": null }
-
GET
/api/1.0/series/(int: series_id)/revisions/
¶ The list of revisions of the series series_id.
GET /api/1.0/series/47/revisions/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "count": 1, "next": null, "previous": null, "results": [ { "version": 1, "cover_letter": null, "patches": [ 120, 121 ] } ] }
-
GET
/api/1.0/series/(int: series_id)/revisions/(int: version)/
¶ The specific
version
of the series series_id.GET /api/1.0/series/47/revisions/1/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "version": 1, "cover_letter": null, "patches": [ 120, 121 ] }
-
GET
/api/1.0/series/(int: series_id)/revisions/(int: version)/mbox/
¶ Retrieve an mbox file that will contain all patches of this revision, in order in which to apply them. This mbox file can be directly piped into
git am
.
$ curl -s http://patchwork.example.com/api/1.0/series/42/revisions/2/mbox/ | git am -3
-
POST
/api/1.0/series/(int: series_id)/revisions/(int: version)/test-results/
¶ - Post test results for this revision.
POST /api/1.0/series/47/revisions/1/test-results/ HTTP/1.1 { "test_name": "checkpatch.pl", "state": "success", "url": "http://jenkins.example.com/logs/47/checkpatch.log", "summary": "total: 0 errors, 0 warnings, 10 lines checked" }
Request JSON Object: - test_name – Required. The name of the test we’re reporting results
for. This uniquely identifies the test. Any subsequent
data sent through this entry point with the same
test_name
will be conflated into the same object. It’s thus possible to create a test result with apending
state when a CI system picks up patches to indicate testing has started and then update the result with the final (state
,url
,summary
) when finished. - state – Required. State of the test results. One of
pending
,success
,warning
orfailure
- url – Optional. A URL where to find the detailed logs of the test run.
- summary – Optional. A summary with some details about the results.
If set, this will be displayed along with the test result
to provide some detailed about the failure. It’s suggested
to use
summary
for something short whileurl
can be used for full logs, which can be rather large.
- test_name – Required. The name of the test we’re reporting results
for. This uniquely identifies the test. Any subsequent
data sent through this entry point with the same
Patches¶
-
GET
/api/1.0/patches/
¶ List of all patches.
GET /api/1.0/patches/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "count": 1392, "next": "http://patchwork.example.com/api/1.0/patches/?page=2", "previous": null, "results": [ { "id": 1, "project": 1, "name": "[RFC,1/4] drm/i915: Define a common data structure for Panel Info", "date": "2014-12-26T10:23:27", "submitter": 1, "state": 1, "content": "<diff content>" }, { "id": 4, "project": 1, "name": "[RFC,2/4] drm/i915: Add a drm_panel over INTEL_SOC_PMIC", "date": "2014-12-26T10:23:28", "submitter": 1, "state": 1, "content": "<diff content>" } ] }
-
GET
/api/1.0/patches/(int: patch_id)/
¶ A specific patch.
GET /api/1.0/patches/120/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json Vary: Accept Allow: GET, HEAD, OPTIONS { "id": 120, "name": "[1/2] drm/i915: Balance context pinning on reset cleanup", "date": "2015-01-13T09:32:24", "submitter": 21, "state": 1, "content": "<diff content>" }
-
GET
/api/1.0/patches/(int: patch_id)/mbox/
¶ Retrieve an mbox file. This mbox file can be directly piped into
git am
.
$ curl -s http://patchwork.example.com/api/1.0/patches/42/mbox/ | git am -3
API Revisions¶
Revision 3
- Add test results entry points:
- /series/${id}/revisions/${version}/test-results/
- Add the submitter, reviewer, submitted_since, updated_since, submitted_before and updated_before query parameters to the list of series entry points.
Revision 2
- Add mbox entry points for both patches and series:
- /patches/${id}/mbox/
- /series/${id}/revisions/${version}/mbox/
- Add a
parameters
field to events and include the revision number to theseries-new-revision
event. - Change /series/${id}/revisions/ to follow the same list system as other entry points. This is technically an API change, but the impact is limited at this early point. Hopefully noone will ever find out.
- Document how lists of objects work.
- Make all DateTime field serialize to ISO 8061 format and not the ECMA 262 subset.
- Add a
since
GET parameter to /projects/${id,linkname}/events/
Revision 1
- Add /projects/${linkname}/events/ entry point.
Revision 0
- Initial revision. Basic objects exposed: api root, projects, series, revisions and patches.