Skip to main content

Unveiling the World of our API Responses

Step into the arena where data meets design - our API responses are crafted to be both intuitive and insightful. Let's explore!


Our Common Format: The Backbone​

Every response from our API adheres to a consistent structure, ensuring you always know what to expect:

Common data format
{
  "version": "1.0",
  "resource_type": "<the resource type here>",
  "data": { ... }
}
  • version: That's our way of saying, "Hey, we're always improving!". Jokes aside, this reflects the current iteration of the resource type.
  • resource_type: Identifies the category of data, offering clarity at first glance.
  • data: The crux of the response, where the requested information resides.

The Fab Five: Our Resource Types​


Single Resource: The Solo Artist​

The single resource type is all about providing a specific piece of data, clear and uncluttered. Expect the data to be a single JSON object.

The single resource
{
"version": "1.0",
"resource_type": "<the resource type here>",
"result_type": "single",
"data": { ... }
}

List Resource: The Party Platter​

Here's where you get a bunch of items in one go. Expect the data to be an array of the particular resource type.

The list resource
{
"version": "1.0",
"resource_type": "<the resource type here>",
"result_type": "list",
"data": [...]
}

Paginated List: The Multi-Page Menu​

When the list is long, we break it down into pages. Expect the data to be an array of the particular resource type.

The list resource
{
"version": "1.0",
"resource_type": "<the resource type here>",
"result_type": "paginated_list",
"pagination": {
    "limit": <number>,
    "page": <number>,
    "total_results": <number>,
    "total_pages": <number>,
},
"data": [...]
}

Deleted Resource: The "Bye-Bye" Message​

When data is removed, this resource type steps in to confirm the action, serving as a clear communication of change. Expect the data to be a single object of the deleted resource. If you need to save it, do so now because we won't be able to deliver it again.

The delete resource
{
"version": "1.0",
"resource_type": "<the resource type here>",
"result_type": "deleted",
"data": {...}
}

Webhook Events: The Newsflash​

These are the updates that pop up with the what, when, and where. Expect the data to be a single JSON object of the particular resource type.

The delete resource
{
"version": "1.0",
"resource_type": "<the resource type here>",
"event": "<event name here>",
"request_timestamp": "<time goes here>"
"data": {...}
}

A Note on Versioning and Semver​

Adapting with Care and Clarity

At Zigned, we understand the importance of predictability and consistency in API responses, especially when it comes to versioning. While we don’t adhere strictly to Semantic Versioning (SemVer), we follow a thoughtful approach to updates and changes.

  • Major and Minor Changes: Our versioning primarily denotes major and minor changes. We aim to provide you with clear information about the nature of each update.
  • Evolving with Compatibility: Our commitment is to ensure that additions to response schemas, such as new data points or statuses, are done compatibly. We won't remove data or keys within the same major version, maintaining a stable and predictable environment for your integrations.
  • Stay Informed, Stay Ahead: Keep an eye on our update logs and documentation. Staying informed helps you adapt smoothly to any changes and leverage new features effectively.

Our goal is to balance innovation with stability. By managing our versioning process thoughtfully, we ensure that your integration with our API remains robust and efficient, even as we evolve and add new capabilities.


Wrapping Up​

Our API's response structure is designed for clarity, efficiency, and user-friendliness. It's about ensuring you have all the information you need, presented in a way that aligns with your workflow. Dive in and discover how our structured responses can streamline your development experience. Happy coding! 🚀