Welcome to the documentation for Fleet, an open-source osquery management server.
Install osquery and Fleet
Get startedCan't find what you need?
SupportThe 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.
An evolving product inherently needs versioning. Most products create a new version with any addition to the product, but the API will work differently in that regard, as new additions to the API won't increase the version.
Fleet will use new versions for breaking changes and deprecating APIs. We release a new version of the API only when a breaking change is introduced.
The format for the API version we've chosen is that of a date with the following format:
<year>-<month>
The date is chosen based on the month the breaking change was introduced.
v1
is the first version of the API. It existed before this text, so it doesn't follow the versioning schema
explained here. We still need to support it for a few months (see below on deprecation). So it'll be treated as an
exception in the logic in the Go code while it exists.
Semantic versioning is great and we are using it in Fleet itself. However, it doesn't necessarily work for APIs since we will not be releasing a new version with every addition, just with breaking changes. So it doesn't align with our needs at the API level.
New versions are deployed when Fleet is released, given the nature of the product. However, not all new versions of Fleet will have a new release for the API.
6 months after the new release has been available.
Let's use an example. In handler.go
we have the following endpoint:
e := NewUserAuthenticatedEndpointer(svc, opts, r, "v1", "2021-11")
// other endpoints here
e.GET("/api/latest/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpoint, getCarveBlockRequest{})
The versions available are v1
and 2021-11
. This means that the following are valid API paths:
/api/latest/fleet/carves/1/block/1234
/api/2021-11/fleet/carves/1/block/1234
Now let's say we want to introduce a breaking change to this API, so we have to specify the version this particular API is being supported and then add the new one that will only be available starting in the new version:
e := NewUserAuthenticatedEndpointer(svc, opts, r, "v1", "2021-11", "2021-12")
// other endpoints here
e.EndingAtVersion("2021-11").GET("/api/latest/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpointDeprecated, getCarveBlockRequestDeprecated{})
e.StartingAtVersion("2021-12").GET("/api/latest/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpoint, getCarveBlockRequest{})
This will mean that the following are all valid paths:
/api/latest/fleet/carves/1/block/1234
/api/2021-11/fleet/carves/1/block/1234
/api/2021-12/fleet/carves/1/block/1234
However, /api/2021-11/fleet/carves/1/block/1234
will be the old API format, and /api/2021-12/fleet/carves/1/block/1234
will be the new API format.
After the date 2022-03
, version 2021-11
(and v1
in this case) will be removed:
e := NewUserAuthenticatedEndpointer(svc, opts, r, "2021-12")
// other endpoints here
e.GET("/api/latest/fleet/carves/{id:[0-9]+}/block/{block_id}", getCarveBlockEndpoint, getCarveBlockRequest{})
This will mean that the following are the only valid paths after this point:
/api/2021-12/fleet/carves/1/block/1234
And the code doesn't have to specify .StartingAtVersion("2021-12")
anymore.
If you notice something we’ve missed, or that could be improved, please click here to edit this page.