Ensuring API Stability: Our Commitment to Clients

At Lab5e, we understand the critical importance of stability and reliability in API integrations. Nothing is more frustrating than integrating a moving target into your backend systems. Our REST API is designed with a strong commitment to maintaining backward compatibility, ensuring that your backend systems and devices continue to function seamlessly as we evolve and improve our service.

Here’s a detailed look at the stability guarantees we give:

Backward Compatibility

We promise that we will do our utmost to not break backwards compability by removing or changing core parts of the service. You can confidently build and scale your applications knowing that the API endpoints you rely on today will continue to work as expected in the future.

• Any new features we add or change in the API will be added as new resources
• Ehanced features on existing request and response objects will be added as optional fields.
• New request parameters are always optional.

Advance Notice for Breaking Changes

While we will do our utmost to avoid breaking changes, there may be instances where they are unavoidable (this could be security issues, external dependencies or changes in standards).

In such cases, we commit to providing our clients with as long a notice as possible and at least six months’ notice before introducing any breaking changes. This extended notice period is designed to give you ample time to make any necessary adjustments to your integrations and deployments, ensuring a smooth transition.

If you need more time, help with upgrades or suggestions for workarounds please do not hesitate to contact us.

What you should do

There are a few simple steps you can do to future-proof your integrations:

• Ignore unknown resources and response objects when using the API.
• Do not assume a particular format for opaque strings like identifiers
• Set aside ample space for string fields like names. They might increase in size some time in the future.

If you use one of the provided API clients or generate your own from the OpenAPI specification this behaviour is already implemented.

Enhanced Stability Options

For clients who require even greater stability, we offer additional options:

• On-Premises Deployment: Host the API on your own infrastructure to have complete control over updates and changes.
• Dedicated Cloud Instances: Utilize dedicated instances in the cloud, providing a stable environment tailored to your specific needs.

These options are ideal for businesses that need to minimize disruptions and maintain a consistent API environment for prolonged periods of time. Please contact us for pricing details.

Core Parts of the API

Our API is structured around several core resources that are fundamental to its operation. the core API structure won’t change. These include:

• Collections: Collections are used to group related devices, making it easier to manage and organize them. Each collection can contain multiple devices, and you can perform operations on the entire collection or individual devices within it.
• Devices: Devices represent the physical (or logical) units that you have deployed. Each device can send and receive data, and you can manage device-specific settings and configurations through the API.
• Gateways: Gateways act as intermediaries that facilitate communication between devices and the cloud. They ensure that data from devices is securely transmitted and received.
• Blobs: Blobs are used to store large binary objects, such as images, sound files or large chunks of data. The API provides endpoints for uploading, downloading, and managing blobs.
• Firmware: The firmware resource allows you to manage firmware images and versions for your devices. You can upload new firmware, assign firmware to devices, and track firmware deployment status.
• Outputs: Outputs define how data from devices is forwarded.

An even more critical element is the ingress endpoints for devices. We will always support the following ingress endpoints in their current form: * UDP: A lightweight, connectionless protocol ideal for time-sensitive transmissions. * CoAP: A specialized transfer protocol for use with constrained devices. * MQTT: A lightweight messaging protocol for small sensors and mobile devices, optimized for high-latency or unreliable networks.

While we may add support for more types of resources, metadata and ingress protocols in the future, these core resources and ingress nodes will remain stable.

Example 1: Adding support for protocol decoding of device payloads

Protocol decoding requires a new resource for configuring the decoders and it would either require a change in the inbox resource that might break existing API clients.

Rather than change the existing resource we’ll introduce a new resource decoding that can inject a decoder in the data handling stream in the service. This is a useful feature for existing API clients but it might not be desired to alter the payloads for an existing system so the decoding step is optional.

Rather than change the existing payload field on messages in the inbox we’ll introduce a new field called decodedPayload. Existing clients won’t be aware of the new field and will ignore it while new clients can use it right away. The existing clients can be updated to use the new field at a later stage.

Example 2: Adding a new gateway

Another example on extending the existing features is if we add support for a new type of IoT network, f.e. LoRaWAN. The following changes would be necessary:

• A new built-in gateway with the gateway type lorawan. Existing API clients does not know this type of gateway so they will ignore it.
• A new configuration and metadata object on the devices named lorawan. Since existing API clients ignore unknown fields and objects they will continue to work as normal.
• Additional optional parameters for the outbox resource to handle the new network. All of these are optional so existing API clients can still use the outbox resource as before with no additional changes.

Example 3: A new kind of collection

If we ever need to change the way collections are created, behave or are defined this will be a big breaking change for all API clients. Rather than replacing the collectionresource we’ll introduce a new resource alongside the existing one.

The old collection resource is at /span/collections/{collectionId} while the new will be placed in /span/v2/collections/{collectionId} and the new collections are mirrored to the old resource. If possible new collections from the old resource are reflected in the old and vice versa.

Existing API clients will still function since they interact with the existing collection resource while new and upgraded API clients will be able to use the full feature set of the new collection resource at the same time.

By adhering to these best practices, we aim to provide a stable and reliable API that you can depend on for your critical business operations.