In Fall of 2019, Samsara released a new generation of API endpoints. This new generation currently coexists with our "
v1" generation, but we are actively reimplementing all our legacy "
v1" endpoints on this new standard. Read on to learn about what's new with this new generation and what it means for your existing applications.
In reviewing feedback on the first generation of our API, we set our sights on standardizing our API and making it easier to use. Here are some of the new API standards you can look forward to:
- Pagination across endpoints
- Human-readable timestamps (RFC 3339 strings)
- Nested objects
- Standard naming conventions and consistent RESTful practices
- More accurate and consistent error codes
- More options for how to consume time-series data
Instead of introducing breaking changes to existing endpoints, we're releasing brand-new endpoints with the above improvements.
This allows you to take advantage of new endpoints on a case-by-case basis rather than having to upgrade an existing application all at once.
All new endpoints will lack the
/v1/ prefix in the endpoint URL. Samsara will be building out all new API features on this new standard.
The new endpoints are available to all API access tokens on any version, so you can use legacy endpoints and new endpoints together in the same application.
All you need is an API token. You can use any Samsara API token, new or existing, to make a call to these new endpoints. You can use the same API token to call both legacy endpoints as well as the new endpoints we're releasing.
Note: These new APIs require that you pass in the API token using the HTTP Authorization header, rather than passing it in as a query parameter.
The root URL for this new API:
https://api.eu.samsara.com/<endpoint> (for EU customers)
The root URL for legacy endpoints (note the
https://api.eu.samsara.com/v1/<endpoint> (for EU customers)
Because the new API and the legacy API have different root URLs, this allows you to take advantage of both using the same API token.
Samsara versions the API if we need to introduce any breaking changes. Versions are tied to your API access token.
The new APIs are available to all token versions. If a breaking change is necessary for either API (legacy or new), we'll release a dated-version. You can choose to upgrade your token to that version at any time, but both sets of APIs (old and new) will always be available to all versions.
You can read more about versioned tokens here.
You can have full-access or read-only API tokens. Any permissions level on an API token will apply to both sets of APIs.
Applications built on the legacy API will continue to operate normally, and we currently do not have any plans to discontinue support for the legacy API. However, we do encourage you to take a look at this new set of endpoints, as we'll be transitioning all legacy endpoints to these new standards. New feature development will also occur on this new API standard.
You can still access the legacy API documentation here.
We do not require customers to migrate code, but we encourage you to explore this new API and consider transitioning over as more endpoints on these new standards become available. We will do all new feature development using this new API structure.
When migrating your code over, please note that the new API no longer has the
/v1 prefix, and there have been some naming changes.
Feedback or questions? Feel free to submit this quick form.
Updated over 1 year ago