Skip to content

Commit 2859427

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

File tree

9 files changed

+514
-14
lines changed

9 files changed

+514
-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: 166 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,128 @@ 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
1230+
of superseded series.
1231+
1232+
::
1233+
1234+
Instance:
1235+
instance.supersedes = [
1236+
'http://example.com/api/series/1/',
1237+
'http://example.com/api/series/2/',
1238+
'http://example.com/api/series/5/'
1239+
]
1240+
1241+
Request:
1242+
PATCH {
1243+
"supersedes": [
1244+
'http://example.com/api/series/1/',
1245+
'http://example.com/api/series/8/'
1246+
]
1247+
}
1248+
1249+
Result:
1250+
instance.supersedes = [
1251+
'http://example.com/api/series/1/',
1252+
'http://example.com/api/series/8/'
1253+
]
1254+
security:
1255+
- basicAuth: []
1256+
- apiKeyAuth: []
1257+
requestBody:
1258+
$ref: '#/components/requestBodies/SeriesUpdate'
1259+
operationId: series_partial_update
1260+
responses:
1261+
'200':
1262+
description: 'Updated series'
1263+
content:
1264+
application/json:
1265+
schema:
1266+
$ref: '#/components/schemas/Series'
1267+
'400':
1268+
description: 'Bad request'
1269+
content:
1270+
application/json:
1271+
schema:
1272+
$ref: '#/components/schemas/Error'
1273+
'403':
1274+
description: 'Forbidden'
1275+
content:
1276+
application/json:
1277+
schema:
1278+
$ref: '#/components/schemas/Error'
1279+
'404':
1280+
description: 'Not found'
1281+
content:
1282+
application/json:
1283+
schema:
1284+
$ref: '#/components/schemas/Error'
1285+
tags:
1286+
- series
1287+
put:
1288+
summary: Update a series.
1289+
description: |
1290+
Only updates the 'supersedes' field of a series. Replaces the whole set
1291+
of superseded series.
1292+
1293+
::
1294+
1295+
Instance:
1296+
instance.supersedes = [
1297+
'http://example.com/api/series/1/',
1298+
'http://example.com/api/series/2/',
1299+
'http://example.com/api/series/5/'
1300+
]
1301+
1302+
Request:
1303+
PUT {
1304+
"supersedes": [
1305+
'http://example.com/api/series/1/',
1306+
'http://example.com/api/series/8/'
1307+
]
1308+
}
1309+
1310+
Result:
1311+
instance.supersedes = [
1312+
'http://example.com/api/series/1/',
1313+
'http://example.com/api/series/8/'
1314+
]
1315+
security:
1316+
- basicAuth: []
1317+
- apiKeyAuth: []
1318+
requestBody:
1319+
$ref: '#/components/requestBodies/SeriesUpdate'
1320+
operationId: series_update
1321+
responses:
1322+
'200':
1323+
description: 'Updated series'
1324+
content:
1325+
application/json:
1326+
schema:
1327+
$ref: '#/components/schemas/Series'
1328+
'400':
1329+
description: 'Bad request'
1330+
content:
1331+
application/json:
1332+
schema:
1333+
$ref: '#/components/schemas/Error'
1334+
'403':
1335+
description: 'Forbidden'
1336+
content:
1337+
application/json:
1338+
schema:
1339+
$ref: '#/components/schemas/Error'
1340+
'404':
1341+
description: 'Not found'
1342+
content:
1343+
application/json:
1344+
schema:
1345+
$ref: '#/components/schemas/Error'
1346+
tags:
1347+
- series
12261348
/api/users:
12271349
get:
12281350
summary: List users.
@@ -1506,6 +1628,14 @@ components:
15061628
application/x-www-form-urlencoded:
15071629
schema:
15081630
$ref: '#/components/schemas/Project'
1631+
SeriesUpdate:
1632+
required: true
1633+
description: |
1634+
A series.
1635+
content:
1636+
application/json:
1637+
schema:
1638+
$ref: '#/components/schemas/SeriesUpdate'
15091639
User:
15101640
required: true
15111641
description: |
@@ -2528,6 +2658,24 @@ components:
25282658
show_dependencies:
25292659
title: Whether the parse dependencies feature is enabled.
25302660
type: boolean
2661+
show_series_versions:
2662+
title: Whether series versioning is enabled.
2663+
type: boolean
2664+
SeriesUpdate:
2665+
type: object
2666+
title: SeriesUpdate
2667+
description: |
2668+
Updatable fields af a series.
2669+
properties:
2670+
supersedes:
2671+
type: array
2672+
items:
2673+
oneOf:
2674+
- type: string
2675+
format: uri
2676+
- type: string
2677+
format: uri-reference
2678+
description: Series deprecated by the current series
25312679
Series:
25322680
type: object
25332681
title: Series
@@ -2613,15 +2761,30 @@ components:
26132761
type: array
26142762
items:
26152763
type: string
2616-
format: url
2764+
format: uri
26172765
readOnly: true
26182766
uniqueItems: true
26192767
dependents:
26202768
title: Dependents
26212769
type: array
26222770
items:
26232771
type: string
2624-
format: url
2772+
format: uri
2773+
readOnly: true
2774+
uniqueItems: true
2775+
supersedes:
2776+
title: Series deprecated by this series
2777+
type: array
2778+
items:
2779+
type: string
2780+
format: uri
2781+
uniqueItems: true
2782+
superseded:
2783+
title: Series that superseded this series
2784+
type: array
2785+
items:
2786+
type: string
2787+
format: uri
26252788
readOnly: true
26262789
uniqueItems: true
26272790
User:

0 commit comments

Comments
 (0)