New API Version

This document describes the changes introduced in the Preview 2024.1 release of the Altair IoT Studio API.

Preview 2024.1

Our API versioning strategy aims to ensure smooth transitions between versions while maintaining backward compatibility for a defined period.

To do this, we use a Preview release to introduce new features and changes in the API. For this Preview phase, the current API and the newly released versions will be supported concurrently. This gives developers time to update their integrations and applications to use the latest features without immediate disruption.

The previous API Version End-of-Life (EOL) date is January 27th, 2025. After this date, the old API version will no longer be available or supported.

Recommendations for Developers: We strongly encourage you to begin testing and migrating to the new API version as soon as possible to ensure compatibility. Use this document and the API Reference to understand the changes introduced and update your applications accordingly.

How to Access the Preview Version

To access the Preview version of the API, add the Prefer: preview=2024.1 header to the requests you make to the API.

Breaking Changes

Breaking changes are not backward compatible, and they may require changes in your applications to work with the new version of the API.

Pagination Support

The following endpoints now return paginated results:
  • GET /spaces
  • GET /spaces/{space}/users
  • GET /spaces/{space}/invitations

Status Codes

The following endpoints to update Property values now return a 200 status code instead of 201:
  • PUT /spaces/{space}/things/{thing-id}/properties
  • PUT /spaces/{space}/things/{thing-id}/properties/{property-name}
  • PUT /spaces/{space}/categories/{category-name}/things/{thing-id}/properties
  • PUT /spaces/{space}/categories/{category-name}/things/{thing-id}/properties/{property-name}

Edge Apps API

Responses no longer include the public attribute if the Edge App is not public (public=false).

Check the Edge Apps API reference.

Packages API Deprecated

The GET /packages and GET /packages/{edge-app-id} endpoints are now deprecated. Use the new Marketplace API instead.

Fixes

The responses of the following endpoints are going to change to be consistent with the current documentation:
  • POST /spaces/{space}/things/{thing-id}/properties-history and POST /spaces/{space}/categories/{category-name}/things/{thing-id}/properties-history now returns an array.
  • GET /spaces/{space}/functions/{function_name}/logs now returns an array.
  • POST /spaces/{space}/objects now returns a 409 status code if the object already exists, instead of overwriting it. The current behavior is to overwrite the object, which is not consistent with the documentation.

New Features

Marketplace API

Note: The changes detailed below do not require the Prefer: preview-2024.1 header as they are new additions.
A new Marketplace API has been added to provide access to public resources available in Altair IoT Studio. The Marketplace API will allow to access public Edge Apps and more types of resources in the future.

  • New endpoints GET /marketplace/edge-apps and GET /marketplace/edge-apps/{edge-app-id} to list and get Edge Apps from the Marketplace. These endpoints are replacing GET /packages and GET /packages/{edge-app-id}, which are now deprecated.

Summary of Changes

The following table summarizes the changes introduced in Preview 2024.1 release:
API Endpoint Description Breaking Change
Spaces GET /spaces Adds pagination support. Yes
Users GET /spaces/{space}/users Adds pagination support. Yes
AnythingDB PUT /spaces/{space}/things/{thing-id}/properties Response status code change from 201 to 200. Yes
AnythingDB PUT /spaces/{space}/things/{thing-id}/properties/{property-name} Response status code change from 201 to 200. Yes
AnythingDB PUT /spaces/{space}/categories/{category-name}/things/{thing-id}/properties Response status code change from 201 to 200. Yes
AnythingDB PUT /spaces/{space}/categories/{category-name}/things/{thing-id}/properties/{property-name} Response status code change from 201 to 200. Yes
AnythingDB POST /spaces/{space}/things/{thing-id}/properties-history Response now returns an array. Yes
AnythingDB POST /spaces/{space}/categories/{category-name}/things/{thing-id}/properties-history Response now returns an array. Yes
Functions GET /spaces/{space}/functions/{function_name}/logs Response now returns an array. Yes
Edge Apps /spaces/{space}/edge-apps/... Responses no longer include the public for non-public Edge Apps. Yes
Packages GET /packages Deprecated. Use GET /marketplace/edge-apps instead. Yes
Packages GET /packages/{edge-app-id} Deprecated. Use GET /marketplace/edge-apps/{edge-app-id} instead. Yes
Marketplace GET /marketplace/edge-apps List Edge Apps from the Marketplace. Note: Prefer: preview=2024.1 header is not required. No
Marketplace GET /marketplace/edge-apps/{edge-app-id} Get Edge App from the Marketplace. Note: Prefer: preview=2024.1 header is not required. No