Skip to content

Introduction to REST API Calls in BizzStream

The BizzStream REST APIs provide a powerful and flexible way to interact with a wide range of functionalities, enabling you to automate workflows, integrate with external systems, and enhance the overall capabilities of your model.

Interacting

Thanks to the widespread adoption of REST as a standard , the API ensures effortless compatibility and interoperability with a diverse range of platforms and technologies. For example, you can interact with the BizzStream REST API using:

  • Postman: A user-friendly and versatile tool, Postman offers a graphical interface that simplifies creating, sending, and analyzing REST API requests. Ideal for both beginners and advanced users, it provides features like saved collections, environment variables, and response visualization, making it a go-to choice for API testing and development.

  • CURL: A powerful command-line tool, CURL is widely used for sending HTTP requests directly from the terminal. It's highly favored in scripting and automation for its flexibility and ability to handle a variety of protocols, making it an essential tool for developers who prefer working in a command-line environment.

Please note that while Postman and CURL are effective tools for making REST calls, these applications are not part of BizzStream's offerings. As such, we do not provide support for either of these external applications. In this documentation, we primarily demonstrate REST calls using CURL, chosen for its widespread use and suitability for a wide range of examples.

Security

Security is paramount in our system; therefore, all REST calls require user authentication to ensure secure access and data integrity. For detailed guidance on obtaining and using authentication credentials, please refer to our comprehensive article on authentication.

For firewall settings from v1 check: firewall documentation.

Return Values

When making API calls, you will use different HTTP methods to tell the server what kind of action you want to perform on a resource (like retrieving data, creating something new, updating existing information, or deleting something). Understanding these common methods will help you interpret the endpoint documentation.

Here are the primary HTTP methods you will encounter in this API and their general purposes:

HTTP Method Purpose in this API
GET Used to retrieve data. GET requests should only fetch data and have no other effect on the server's state. Think of it as reading information.
POST Used to send data to the server, most commonly to create new resources. It can also be used for actions that don't neatly fit into the other methods.
PUT Used to update or replace an existing resource. When you send a PUT request with a body, you are typically sending the complete, updated representation of the resource to be stored at the target URL.
DELETE Used to request the removal of a specific resource identified by the URL.

By looking at the HTTP method specified for an endpoint in the documentation, you can immediately understand the primary action that endpoint is designed to perform.

For more methods and information you can look at the Mozilla website.

  • Please note that not all methods might be supported by the BizzStream API

Error return value

When your API calls don't go exactly as planned, the server sends back a standardized error message. This isn't just a generic "something went wrong" note; it's a structured piece of information designed to help you quickly diagnose and resolve issues. These structured messages are invaluable for efficient diagnosis and resolution of problems.

The Anatomy of an Error Message

Here's a typical example of what an error response might look like in your script:

{
  "status": "error",
  "error": "validation_error",
  "description": "Body error: \"value\" must be of type object",
  "message": "The data submitted is not in the expected format.",
  "userDescription": "Looks like there's an issue with the data you provided. Please double-check the input and try again."
}
Let's break down the key fields you'll encounter:
"status" "error": This is your immediate signal that the request was unsuccessful. If this field is "success", you know everything went smoothly.
"error" Think of this as the API's internal error code. It's a concise, machine-readable string (like "validation_error", "internal_server_error", or "token_not_found") that you can use in your code to trigger specific logic. It tells you what kind of problem occurred.
"description" This provides a more technical, detailed explanation of the error. It's primarily for developers to understand the specifics of the issue.
"message" Often a slightly more generalized or concise version of the description, suitable for logging or initial developer alerts.
"userDescription" This field is intended for user-facing feedback. If present, it contains a clear, non-technical message that can be displayed directly to your application's users without requiring technical interpretation.
"validationErrors" This is not always sent but can be found in some casese. This is an array containing even more granular details, pointing to specific fields in your request body that failed validation (e.g., "workflow.name" is missing).