|
1 | 1 | # API versioning |
2 | 2 |
|
3 | | -All of the Fleet API routes currently support `v1` in the URL path. |
4 | | - |
5 | | -When Fleet 5 is released, the Fleet API will use date versioning (specified below) and support for `v1` will be removed. |
6 | | - |
7 | | -## Why do we need to version the API? |
8 | | - |
9 | | -The API is a product, just like fleetctl and the web UI. It has its users, mostly fleetctl and the web UI, but third-party developers also work with it. |
10 | | - |
11 | | -An evolving product inherently needs versioning. Most products create a new version with any addition to the product, but |
12 | | -the API will work differently in that regard, as new additions to the API won't increase the version. |
13 | | - |
14 | | -Fleet will use new versions for breaking changes and deprecating APIs. We |
15 | | -release a new version of the API only when introducing a breaking change. |
16 | | - |
17 | | -## What kind of versioning will we use for the API? |
18 | | - |
19 | | -The format for the API version we've chosen is that of a date with the following format: |
20 | | - |
21 | | -``` |
22 | | -<year>-<month> |
23 | | -``` |
24 | | - |
25 | | -The date is chosen based on the month we introduce the breaking change. |
26 | | - |
27 | | -## Why is v1 still available at the time of this writing? |
28 | | - |
29 | | -`v1` is the first version of the API. It existed before this text, so it doesn't follow the versioning schema |
30 | | -explained here. We still need to support it for a few months (see below on deprecation). So it'll be treated as an |
31 | | -exception in the logic in the Go code while it exists. |
32 | | - |
33 | | -## Why not semantic versioning? |
34 | | - |
35 | | -Semantic versioning is great, and we are using it in Fleet itself. However, it doesn't necessarily work for APIs since we |
36 | | -will not be releasing a new version with every addition, just with breaking changes. So it doesn't align with our |
37 | | -needs at the API level. |
38 | | - |
39 | | -## How are API releases aligned with regular Fleet releases? |
40 | | - |
41 | | -New versions are deployed when Fleet is released, given the nature of the product. However, not all new versions of |
42 | | -Fleet will have a new release for the API. |
43 | | - |
44 | | -## How long do I have until you remove a deprecated API? |
45 | | - |
46 | | -Six months after the new release has been available. |
47 | | - |
48 | | -## How are breaking changes introduced? (Mostly for developers) |
49 | | - |
50 | | -Let's use an example. In `handler.go`, we have the following endpoint: |
51 | | - |
52 | | -```go |
53 | | -e := NewUserAuthenticatedEndpointer(svc, opts, r, "v1", "2021-11") |
54 | | - |
55 | | -// other endpoints here |
56 | | - |
57 | | -e.GET("/api/v1/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpoint, getCarveBlockRequest{}) |
58 | | -``` |
59 | | - |
60 | | -The versions available are `v1` and `2021-11`. This means that the following are valid API paths: |
61 | | - |
62 | | -``` |
63 | | -/api/v1/fleet/carves/1/block/1234 |
64 | | -/api/2021-11/fleet/carves/1/block/1234 |
65 | | -``` |
66 | | - |
67 | | -Now let's say we want to introduce a breaking change to this API, so we have to specify the version this particular API |
68 | | -is being supported and then add the new one that will only be available starting in the new version: |
69 | | - |
70 | | -```go |
71 | | -e := NewUserAuthenticatedEndpointer(svc, opts, r, "v1", "2021-11", "2021-12") |
72 | | - |
73 | | -// other endpoints here |
74 | | - |
75 | | -e.EndingAtVersion("2021-11").GET("/api/v1/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpointDeprecated, getCarveBlockRequestDeprecated{}) |
76 | | -e.StartingAtVersion("2021-12").GET("/api/v1/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpoint, getCarveBlockRequest{}) |
77 | | -``` |
78 | | - |
79 | | -This will mean that the following are all valid paths: |
80 | | - |
81 | | -``` |
82 | | -/api/v1/fleet/carves/1/block/1234 |
83 | | -/api/2021-11/fleet/carves/1/block/1234 |
84 | | -/api/2021-12/fleet/carves/1/block/1234 |
85 | | -``` |
86 | | - |
87 | | -However, `/api/2021-11/fleet/carves/1/block/1234` will be the old API format, and `/api/2021-12/fleet/carves/1/block/1234` |
88 | | -will be the new API format. |
89 | | - |
90 | | -After the date `2022-03`, version `2021-11` (and `v1` in this case) will be removed: |
91 | | - |
92 | | - |
93 | | -```go |
94 | | -e := NewUserAuthenticatedEndpointer(svc, opts, r, "2021-12") |
95 | | - |
96 | | -// other endpoints here |
97 | | - |
98 | | -e.GET("/api/v1/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpoint, getCarveBlockRequest{}) |
99 | | -``` |
100 | | - |
101 | | -This will mean that the following are the only valid paths after this point: |
102 | | - |
103 | | -``` |
104 | | -/api/2021-12/fleet/carves/1/block/1234 |
105 | | -``` |
106 | | - |
107 | | -And the code doesn't have to specify `.StartingAtVersion("2021-12")` anymore. |
| 3 | +All of the [Fleet API routes]([url](https://fleetdm.com/docs/rest-api/rest-api)) currently include `v1` in the URL path to identify which iteration of the API is being used. This allows us to release new features, improvements, or breaking changes in the future under a different version (like `/v2/`) without disrupting existing clients that still rely on the previous version. By versioning our API, we can manage changes in a predictable, structured way. This approach provides a clear upgrade path for developers and prevents confusion by standardizing how changes are communicated, documented, and ultimately adopted by API consumers. |
108 | 4 |
|
109 | 5 | <meta name="pageOrderInSection" value="900"> |
110 | 6 | <meta name="description" value="Learn about how and why the Fleet API is versioned."> |
0 commit comments