Skip to content

Commit 850b794

Browse files
authored
WPB-6177 document steps for creating new API version (#3817)
1 parent 1824dee commit 850b794

File tree

4 files changed

+25
-23
lines changed

4 files changed

+25
-23
lines changed

changelog.d/4-docs/WPB-6177

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Documentation for creating a new API version updated

docs/src/developer/developer/api-versioning.md

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -107,15 +107,20 @@ non-overlapping version ranges.
107107

108108
When making the client API version bump, i.e., when finalising a version, there
109109
are several steps to make apart from deciding what endpoint changes are part of
110-
the version:
111-
112-
- In `wire-api` extend the `Version` type with a new version by appending the
113-
new version to the end, e.g., by adding `V6`.
114-
- In the same `Version` module update the `developmentVersions` value to list
115-
only the new version,
116-
- Consider updating the `backendApiVersion` value in Stern, which is
117-
unit-tested by checking if it is listed as supported in the response to `GET
118-
/api-version`.
110+
the version. In these example we assume that version `V6` should be finalized and `V7` should be created:
111+
112+
- Run wire-server and download the `swagger.json` of the current development version, e.g. with the following command: `curl localhost:8080/v6/api/swagger.json | jq > swagger-v6.json` and copy the file to `services/brig/docs/swagger-v6.json`.
113+
- In `wire-api` extend the `Version` type with a new version by appending the
114+
new version to the end.
115+
- In the same `Version` module update the `developmentVersions` value to list
116+
only the new version.
117+
- In `services/brig/src/Brig/API/Public.hs`
118+
- update `versionedSwaggerDocsAPI` so that the finalized version points to the pregenerated swagger
119+
- and `internalEndpointsSwaggerDocsAPI` so that the finalized version `V6`, the new version `V7`, as well as the unversioned path point to the swagger of the internal API, and the previous latest stable version V5 points to an empty swagger.
120+
- Set the version for `gDefaultAPIVersion` in `integration/test/Testlib/Env.hs` to 7.
121+
- Consider updating the `backendApiVersion` value in Stern, which is
122+
unit-tested by checking if it is listed as supported in the response to `GET
123+
/api-version`.
119124

120125
### Examples of endpoint evolution
121126

services/brig/src/Brig/API/Public.hs

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -197,12 +197,12 @@ versionedSwaggerDocsAPI (Just (VersionNumber V6)) =
197197
& S.info . S.description ?~ $(embedText =<< makeRelativeToProject "docs/swagger.md")
198198
& S.servers .~ [S.Server ("/" <> toUrlPiece V6) Nothing mempty]
199199
& cleanupSwagger
200-
versionedSwaggerDocsAPI (Just (VersionNumber V0)) = swaggerPregenUIServer $(pregenSwagger V0)
201-
versionedSwaggerDocsAPI (Just (VersionNumber V1)) = swaggerPregenUIServer $(pregenSwagger V1)
202-
versionedSwaggerDocsAPI (Just (VersionNumber V2)) = swaggerPregenUIServer $(pregenSwagger V2)
203-
versionedSwaggerDocsAPI (Just (VersionNumber V3)) = swaggerPregenUIServer $(pregenSwagger V3)
204-
versionedSwaggerDocsAPI (Just (VersionNumber V4)) = swaggerPregenUIServer $(pregenSwagger V4)
205200
versionedSwaggerDocsAPI (Just (VersionNumber V5)) = swaggerPregenUIServer $(pregenSwagger V5)
201+
versionedSwaggerDocsAPI (Just (VersionNumber V4)) = swaggerPregenUIServer $(pregenSwagger V4)
202+
versionedSwaggerDocsAPI (Just (VersionNumber V3)) = swaggerPregenUIServer $(pregenSwagger V3)
203+
versionedSwaggerDocsAPI (Just (VersionNumber V2)) = swaggerPregenUIServer $(pregenSwagger V2)
204+
versionedSwaggerDocsAPI (Just (VersionNumber V1)) = swaggerPregenUIServer $(pregenSwagger V1)
205+
versionedSwaggerDocsAPI (Just (VersionNumber V0)) = swaggerPregenUIServer $(pregenSwagger V0)
206206
versionedSwaggerDocsAPI Nothing = allroutes (throwError listAllVersionsResp)
207207
where
208208
allroutes ::
@@ -250,15 +250,11 @@ internalEndpointsSwaggerDocsAPI service examplePort swagger (Just (VersionNumber
250250
swagger
251251
& adjustSwaggerForInternalEndpoint service examplePort
252252
& cleanupSwagger
253-
internalEndpointsSwaggerDocsAPI service examplePort swagger (Just (VersionNumber V4)) =
254-
swaggerSchemaUIServer $
255-
swagger
256-
& adjustSwaggerForInternalEndpoint service examplePort
257-
& cleanupSwagger
258-
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V0)) = emptySwagger
259-
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V1)) = emptySwagger
260-
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V2)) = emptySwagger
253+
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V4)) = emptySwagger
261254
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V3)) = emptySwagger
255+
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V2)) = emptySwagger
256+
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V1)) = emptySwagger
257+
internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V0)) = emptySwagger
262258
internalEndpointsSwaggerDocsAPI service examplePort swagger Nothing =
263259
internalEndpointsSwaggerDocsAPI service examplePort swagger (Just maxBound)
264260

services/brig/src/Brig/API/Public/Swagger.hs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ emptySwagger =
127127
swaggerSchemaUIServer $
128128
mempty @S.OpenApi
129129
& S.info . S.description
130-
?~ "There is no Swagger documentation for this version. Please refer to v3 or later."
130+
?~ "There is no Swagger documentation for this version. Please refer to v5 or later."
131131

132132
{- FUTUREWORK(fisx): there are a few things that need to be fixed before this schema collection
133133
is of any practical use!

0 commit comments

Comments
 (0)