Skip to content

Commit 393a3ba

Browse files
victor-accarinivictor-accarini
committed
docs: update documentation with series versioning
Signed-off-by: Victor Accarini <[email protected]>
1 parent beca69f commit 393a3ba

File tree

9 files changed

+424
-14
lines changed

9 files changed

+424
-14
lines changed

‎docs/.DS_Store

8 KB
Binary file not shown.

‎docs/api/rest/index.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ If all you want is reference guides, skip straight to :ref:`rest-api-schemas`.
4343
The API version was bumped to v1.3 in Patchwork v3.1. The older APIs are
4444
still supported. For more information, refer to :ref:`rest-api-versions`.
4545

46+
.. versionchanged:: 3.2
47+
48+
The API version was bumped to v1.4 in Patchwork v3.2. The older APIs are
49+
still supported. For more information, refer to :ref:`rest-api-versions`.
50+
4651
Getting Started
4752
---------------
4853

@@ -79,7 +84,7 @@ well-supported. To repeat the above example using `requests`:, run
7984
$ python
8085
>>> import json
8186
>>> import requests
82-
>>> r = requests.get('https://patchwork.example.com/api/1.3/')
87+
>>> r = requests.get('https://patchwork.example.com/api/1.4/')
8388
>>> print(json.dumps(r.json(), indent=2))
8489
{
8590
"bundles": "https://patchwork.example.com/api/1.4/bundles/",

‎docs/api/schemas/latest/patchwork.yaml

Lines changed: 136 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1203,7 +1203,7 @@ paths:
12031203
title: ID
12041204
type: integer
12051205
get:
1206-
summary: Show a series.
1206+
summary: Return the details of a series.
12071207
description: |
12081208
Retrieve a series by its ID.
12091209
A series is a collection of patches with an optional cover letter.
@@ -1223,6 +1223,98 @@ paths:
12231223
$ref: '#/components/schemas/Error'
12241224
tags:
12251225
- series
1226+
patch:
1227+
summary: Partially update a series.
1228+
description: |
1229+
Only updates the 'supersedes' field of a series. Replaces the whole set of
1230+
superseded series.
1231+
1232+
Example:
1233+
Instance:
1234+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/2/", "http://example.com/api/series/5/"]
1235+
Request:
1236+
PATCH {"supersedes": ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]}
1237+
Result:
1238+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]
1239+
security:
1240+
- basicAuth: []
1241+
- apiKeyAuth: []
1242+
requestBody:
1243+
$ref: '#/components/requestBodies/SeriesUpdate'
1244+
operationId: series_partial_update
1245+
responses:
1246+
'200':
1247+
description: 'Updated series'
1248+
content:
1249+
application/json:
1250+
schema:
1251+
$ref: '#/components/schemas/Series'
1252+
'400':
1253+
description: 'Bad request'
1254+
content:
1255+
application/json:
1256+
schema:
1257+
$ref: '#/components/schemas/Error'
1258+
'403':
1259+
description: 'Forbidden'
1260+
content:
1261+
application/json:
1262+
schema:
1263+
$ref: '#/components/schemas/Error'
1264+
'404':
1265+
description: 'Not found'
1266+
content:
1267+
application/json:
1268+
schema:
1269+
$ref: '#/components/schemas/Error'
1270+
tags:
1271+
- series
1272+
put:
1273+
summary: Update a series.
1274+
description: |
1275+
Only updates the 'supersedes' field of a series. Replaces the whole set of
1276+
superseded series.
1277+
1278+
Example:
1279+
Instance:
1280+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/2/", "http://example.com/api/series/5/"]
1281+
Request:
1282+
PUT {"supersedes": ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]}
1283+
Result:
1284+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]
1285+
security:
1286+
- basicAuth: []
1287+
- apiKeyAuth: []
1288+
requestBody:
1289+
$ref: '#/components/requestBodies/SeriesUpdate'
1290+
operationId: series_update
1291+
responses:
1292+
'200':
1293+
description: 'Updated series'
1294+
content:
1295+
application/json:
1296+
schema:
1297+
$ref: '#/components/schemas/Series'
1298+
'400':
1299+
description: 'Bad request'
1300+
content:
1301+
application/json:
1302+
schema:
1303+
$ref: '#/components/schemas/Error'
1304+
'403':
1305+
description: 'Forbidden'
1306+
content:
1307+
application/json:
1308+
schema:
1309+
$ref: '#/components/schemas/Error'
1310+
'404':
1311+
description: 'Not found'
1312+
content:
1313+
application/json:
1314+
schema:
1315+
$ref: '#/components/schemas/Error'
1316+
tags:
1317+
- series
12261318
/api/users:
12271319
get:
12281320
summary: List users.
@@ -1506,6 +1598,14 @@ components:
15061598
application/x-www-form-urlencoded:
15071599
schema:
15081600
$ref: '#/components/schemas/Project'
1601+
SeriesUpdate:
1602+
required: true
1603+
description: |
1604+
A series.
1605+
content:
1606+
application/json:
1607+
schema:
1608+
$ref: '#/components/schemas/SeriesUpdate'
15091609
User:
15101610
required: true
15111611
description: |
@@ -2528,6 +2628,24 @@ components:
25282628
show_dependencies:
25292629
title: Whether the parse dependencies feature is enabled.
25302630
type: boolean
2631+
show_series_versions:
2632+
title: Whether series versioning is enabled.
2633+
type: boolean
2634+
SeriesUpdate:
2635+
type: object
2636+
title: SeriesUpdate
2637+
description: |
2638+
Updatable fields af a series.
2639+
properties:
2640+
supersedes:
2641+
type: array
2642+
items:
2643+
oneOf:
2644+
- type: string
2645+
format: uri
2646+
- type: string
2647+
format: uri-reference
2648+
description: Series deprecated by the current series
25312649
Series:
25322650
type: object
25332651
title: Series
@@ -2613,15 +2731,30 @@ components:
26132731
type: array
26142732
items:
26152733
type: string
2616-
format: url
2734+
format: uri
26172735
readOnly: true
26182736
uniqueItems: true
26192737
dependents:
26202738
title: Dependents
26212739
type: array
26222740
items:
26232741
type: string
2624-
format: url
2742+
format: uri
2743+
readOnly: true
2744+
uniqueItems: true
2745+
supersedes:
2746+
title: Series deprecated by this series
2747+
type: array
2748+
items:
2749+
type: string
2750+
format: uri
2751+
uniqueItems: true
2752+
superseded:
2753+
title: Series that superseded this series
2754+
type: array
2755+
items:
2756+
type: string
2757+
format: uri
26252758
readOnly: true
26262759
uniqueItems: true
26272760
User:

‎docs/api/schemas/patchwork.j2

Lines changed: 142 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1228,7 +1228,7 @@ paths:
12281228
title: ID
12291229
type: integer
12301230
get:
1231-
summary: Show a series.
1231+
summary: Return the details of a series.
12321232
description: |
12331233
Retrieve a series by its ID.
12341234
A series is a collection of patches with an optional cover letter.
@@ -1248,6 +1248,100 @@ paths:
12481248
$ref: '#/components/schemas/Error'
12491249
tags:
12501250
- series
1251+
{% if version >= (1, 4) %}
1252+
patch:
1253+
summary: Partially update a series.
1254+
description: |
1255+
Only updates the 'supersedes' field of a series. Replaces the whole set of
1256+
superseded series.
1257+
1258+
Example:
1259+
Instance:
1260+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/2/", "http://example.com/api/series/5/"]
1261+
Request:
1262+
PATCH {"supersedes": ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]}
1263+
Result:
1264+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]
1265+
security:
1266+
- basicAuth: []
1267+
- apiKeyAuth: []
1268+
requestBody:
1269+
$ref: '#/components/requestBodies/SeriesUpdate'
1270+
operationId: series_partial_update
1271+
responses:
1272+
'200':
1273+
description: 'Updated series'
1274+
content:
1275+
application/json:
1276+
schema:
1277+
$ref: '#/components/schemas/Series'
1278+
'400':
1279+
description: 'Bad request'
1280+
content:
1281+
application/json:
1282+
schema:
1283+
$ref: '#/components/schemas/Error'
1284+
'403':
1285+
description: 'Forbidden'
1286+
content:
1287+
application/json:
1288+
schema:
1289+
$ref: '#/components/schemas/Error'
1290+
'404':
1291+
description: 'Not found'
1292+
content:
1293+
application/json:
1294+
schema:
1295+
$ref: '#/components/schemas/Error'
1296+
tags:
1297+
- series
1298+
put:
1299+
summary: Update a series.
1300+
description: |
1301+
Only updates the 'supersedes' field of a series. Replaces the whole set of
1302+
superseded series.
1303+
1304+
Example:
1305+
Instance:
1306+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/2/", "http://example.com/api/series/5/"]
1307+
Request:
1308+
PUT {"supersedes": ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]}
1309+
Result:
1310+
instance.supersedes = ["http://example.com/api/series/1/", "http://example.com/api/series/8/"]
1311+
security:
1312+
- basicAuth: []
1313+
- apiKeyAuth: []
1314+
requestBody:
1315+
$ref: '#/components/requestBodies/SeriesUpdate'
1316+
operationId: series_update
1317+
responses:
1318+
'200':
1319+
description: 'Updated series'
1320+
content:
1321+
application/json:
1322+
schema:
1323+
$ref: '#/components/schemas/Series'
1324+
'400':
1325+
description: 'Bad request'
1326+
content:
1327+
application/json:
1328+
schema:
1329+
$ref: '#/components/schemas/Error'
1330+
'403':
1331+
description: 'Forbidden'
1332+
content:
1333+
application/json:
1334+
schema:
1335+
$ref: '#/components/schemas/Error'
1336+
'404':
1337+
description: 'Not found'
1338+
content:
1339+
application/json:
1340+
schema:
1341+
$ref: '#/components/schemas/Error'
1342+
tags:
1343+
- series
1344+
{% endif %}
12511345
/api/{{ version_url }}users:
12521346
get:
12531347
summary: List users.
@@ -1547,6 +1641,16 @@ components:
15471641
application/x-www-form-urlencoded:
15481642
schema:
15491643
$ref: '#/components/schemas/Project'
1644+
{% if version >= (1, 4) %}
1645+
SeriesUpdate:
1646+
required: true
1647+
description: |
1648+
A series.
1649+
content:
1650+
application/json:
1651+
schema:
1652+
$ref: '#/components/schemas/SeriesUpdate'
1653+
{% endif %}
15501654
User:
15511655
required: true
15521656
description: |
@@ -2621,6 +2725,26 @@ components:
26212725
show_dependencies:
26222726
title: Whether the parse dependencies feature is enabled.
26232727
type: boolean
2728+
show_series_versions:
2729+
title: Whether series versioning is enabled.
2730+
type: boolean
2731+
{% endif %}
2732+
{% if version >= (1, 4) %}
2733+
SeriesUpdate:
2734+
type: object
2735+
title: SeriesUpdate
2736+
description: |
2737+
Updatable fields af a series.
2738+
properties:
2739+
supersedes:
2740+
type: array
2741+
items:
2742+
oneOf:
2743+
- type: string
2744+
format: uri
2745+
- type: string
2746+
format: uri-reference
2747+
description: Series deprecated by the current series
26242748
{% endif %}
26252749
Series:
26262750
type: object
@@ -2710,15 +2834,30 @@ components:
27102834
type: array
27112835
items:
27122836
type: string
2713-
format: url
2837+
format: uri
27142838
readOnly: true
27152839
uniqueItems: true
27162840
dependents:
27172841
title: Dependents
27182842
type: array
27192843
items:
27202844
type: string
2721-
format: url
2845+
format: uri
2846+
readOnly: true
2847+
uniqueItems: true
2848+
supersedes:
2849+
title: Series deprecated by this series
2850+
type: array
2851+
items:
2852+
type: string
2853+
format: uri
2854+
uniqueItems: true
2855+
superseded:
2856+
title: Series that superseded this series
2857+
type: array
2858+
items:
2859+
type: string
2860+
format: uri
27222861
readOnly: true
27232862
uniqueItems: true
27242863
{% endif %}

‎docs/api/schemas/v1.0/patchwork.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -916,7 +916,7 @@ paths:
916916
title: ID
917917
type: integer
918918
get:
919-
summary: Show a series.
919+
summary: Return the details of a series.
920920
description: |
921921
Retrieve a series by its ID.
922922
A series is a collection of patches with an optional cover letter.

0 commit comments

Comments
 (0)