ZEDEDA API Overview

Updated

ZEDEDA’s RESTful API enables you to interact programmatically with ZEDEDA Cloud. Using the ZEDEDA API, you can create custom automations and integrations according to your individual business needs. 

This overview describes the available APIs and what to expect from their different versions.

ZEDEDA offers the following web services:

  • ZEDEDA Storage Service
  • ZEDEDA Job Service
  • ZEDEDA Diagnostic Service
  • ZEDEDA IAM Service
  • ZEDEDA Edge Application Service
  • ZEDEDA Edge Network Service
  • ZEDEDA Edge Node Service
  • ZEDEDA Orchestrator Service

Each of these web services features its own set of APIs (also referred to as “objects” in this documentation). Each of a service’s objects has a specification. For example, the ZEDEDA Edge Network Service has the EdgeNetworkConfiguration API object.

You can navigate between services to see their specifications using the “Select a definition” dropdown on our API documentation top nav bar.

To see specifications for our APIs, go to our API documentation.

API versions and differences

Each of our APIs offers a version 1 (V1), and some offer a version 2 (V2). The primary differences between V1 and V2 include updates, improvements, and changes in the newer version.

NOTE: While V1 and V2 are offered in parallel, V1 is deprecated in favor of V2. V1 is still available, but you should plan to migrate to the latest version for better performance and compatibility with new features.

Areas of distinction between V1 and V2 follow:

  • New Features and Functionalities
    • V1: The initial version contains the core set of features and functionalities.
    • V2: Introduces new or enhanced features that might not have been available in V1. These can include new endpoints, expanded functionality, or additional resource representations.
  • Breaking Changes
    • V1: Establishes the foundation for API consumers as the first version. Upgrading from V1 to V2 can introduce breaking changes.
    • V2: Might deprecate or significantly alter several features from V1. These changes could involve modifications to how certain resources are structured, changes in request/response formats, or even removal of older endpoints.
  • Improved Security
    • V1: Security standards might be lower or older (for example, using older authentication mechanisms like API keys).
    • V2: Often introduces updated security features, such as better OAuth2 implementations, JWT (JSON Web Tokens), and enhanced data validation.
  • Performance Enhancements
    • V1: Performance might not be optimized, especially if the initial version did not focus on scaling or efficiency.
    • V2: Typically includes performance improvements like better caching strategies, reduced payload sizes, or more efficient query handling.
  • Standardization and Consistency
    • V1: Might lack consistency in naming conventions, error handling, or response structures.
    • V2: Often focuses on standardizing these aspects across the API, making it easier for developers to interact with the API. Common improvements include using standardized error codes or improved documentation.
  • Backward Compatibility
    • V1: Is the original version so doesn’t need to ensure compatibility with any earlier versions.
    • V2: Might not maintain backward compatibility. V2 could either introduce a completely new set of endpoints or maintain support for V1 endpoints, depending on the versioning strategy.
  • Deprecation of Old Features
    • V1: Some endpoints or fields might become deprecated, meaning they are no longer recommended for use.
    • V2: Does not include some old features, encouraging users to migrate to newer endpoints or features introduced in V2.
  • From Synchronous to Asynchronous

From synchronous to asynchronous deployment requests

In an effort to improve performance and scalability, we have upgraded our app instance APIs from V1 to V2. One of the key changes introduced in V2 is the transition from synchronous to asynchronous processing for app instance deployment requests.


V1 API: synchronous deployment requests

In V1, app instance deployment requests were handled synchronously. This meant that when a request was submitted, the client had to wait for the entire deployment process to complete before receiving a response. This synchronous processing could lead to longer response times and potential bottlenecks, especially during periods of high demand.

Challenges with V1 included the following:

  • Clients were forced to wait for the deployment to finish, leading to potential timeouts.
  • The system could become overwhelmed during peak loads, reducing its ability to scale efficiently.
  • Resources remained tied up for the duration of the process, affecting performance.

V2 API: asynchronous deployment requests

To overcome the V1 limitations, V2 uses asynchronous processing. Now, when an app instance deployment request is submitted, the server immediately returns a response acknowledging the request and begins the deployment in the background. The client is not required to wait for the full deployment to complete.

Benefits of V2 asynchronous processing include the following:

  • Improved responsiveness: The client receives an acknowledgment almost instantly, without having to wait for the deployment to finish.
  • Enhanced scalability: The server can handle a higher volume of requests without being blocked by longer-running operations.
  • Better resource management: Resources are allocated efficiently, ensuring smoother operation even during peak usage times.

A summary follows of the V2 asynchronous workflow: 

  1. Request submission: The client sends a deployment request to the API.
  2. Immediate acknowledgment: The server immediately responds with an acknowledgment, including a request ID or a tracking URL.
  3. Background processing: The deployment process runs asynchronously in the background.
  4. Status updates: The client can query the status of the deployment using the request ID or listen for a callback/notification once the process is complete.

Upgrading versions

When we release a new API version for an object (such as EdgeNetworkConfiguration in the ZEDEDA Edge Network Service), we upgrade specific endpoints for that object. This ensures the stability and convenience of our APIs throughout the upgrade process.

The versioning approach is object-specific and gradual: 

  • Object-Specific Versioning: When a new API version is released, all existing endpoints related to a specific object (e.g., app instances, network configurations) are upgraded. Other objects that are not part of the upgrade retain their current version and functionality.
  • Gradual Updates: This selective upgrade method allows ZEDEDA Cloud to introduce new features, optimizations, or architectural changes for specific components without affecting unrelated objects. As a result, the system can evolve in a more controlled and efficient manner.

For example, if the App Instance endpoints are upgraded from V1 to V2, only the endpoints handling operations like creation, deployment, and status updates for App Instances are affected. Other objects, such as Network Settings or User Profiles, remain unchanged and continue to operate on their existing versions. This object-specific versioning ensures that the API remains stable and backward-compatible while allowing targeted enhancements where needed.


Migrating from V1 to V2

When you migrate your automations and integrations to the V2 APIs, ensure that you are fully familiar with accessing the V2 specification.

In some cases, you might just need to change the version number in the URI path: 

  • POST /api/v1/edgeDevice/register
  • POST /api/v2/edgeDevice/register

But in some cases, you might need to change more, and the payload might be different:

  • GET /api/v1/edgedevice/ext/check
  • GET /api/v2/edgedevice/id/{uuid}/ext/check

If something stops working when you upgrade, review the specifications for that API. If you don't find a solution there, contact support.

NOTE: While V1 and V2 are offered in parallel, V1 is deprecated in favor of V2. V1 is still available, but you should plan to migrate to the latest version for better performance and compatibility with new features.

Accessing V1 and V2 API docs

V2 endpoint specifications can be found alongside the specifications of their V1 counterparts in our Swagger documentation. Note that you can test directly against your own cluster using the following syntax: 

https://zedcontrol.{YOUR_CLUSTER_NAME}.zededa.net/api/v1/docs/


Next steps

See using the ZEDEDA API.

Was this article helpful?
0 out of 0 found this helpful