REST API

While the gRPC API provides low latency and excellent scalability, the REST API provide a traditional integration path for web-based applications. The REST API has been generated from the gRPC API definition, and uses JSON transcoding to handle requests.

OpenAPI specification

You can download the OpenAPI specification from the website.

This specification provides a comprehensive overview of the available endpoints, request/response formats, and authentication requirements.

You can use the OpenAPI specification with tools of your choosing like Insomnia or Postman.

1. Download the OpenAPI YAML file.
2. Import the file into your tool of choice, like Insomnia or Postman.
3. Start making API calls directly from the tool.

API reference

If you'd like to try the REST APIs live in your browser, the API reference allows you to make API calls. You'll need a valid JWT token to do so. Insert the token into the page and click the SEND API REQUEST button:

Authentication

BidZenith uses Bearer tokens to authorize requests, which are obtained using the OAuth 2.0 Client Credentials Flow, using the client_id and client_secret generated upon creating an app client. Consult the OAuth documentation for steps on how to create tokens.

BidZenith expects the Bearer token to be included via the HTTP Authorization header in all API requests to the server. When using curl, it looks like the following:

curl -H 'Authorization: Bearer <token>' https://app.bidzenith.com/v1/campaigns

Authorization

When creating an app client, a collection of roles are specified that determine what the app client has access to. These roles are encoded within the JSON Web Token (JWT) bearer token, and can be viewed using jwt.io.

important

In all cases, if an app client does not have permission to do something, you'll get a 403 Forbidden error.

Pagination

Some APIs support pagination. Pagination is performed with a pageToken parameter. This parameter is an opaque string whose format can and will change over time, so its format should not be inspected or relied upon.

A nextPageToken property in the response of APIs that support pagination indicates whether more records can be fetched by using the same query, and the value of nextPageToken assigned to pageToken.

note

You can change the number of items to be returned with the pageSize parameter, defaulting to 10. This can be a value between 1 and 100.

Errors

We don't usually have any trouble on our end, but when we do we'll let you know!

The BidZenith API uses the following HTTP status codes:

Code	Text	Description
400	Bad Request	Your request is malformed in some way. The response usually indicates what's wrong.
401	Unauthorized	Your request does not have valid authentication credentials for the operation.
403	Forbidden	Your request is not authorized to perform the operation.
404	Not Found	The specified resource was not found
408	Request Timeout	Your request was cancelled, typically by you.
409	Conflict	Your request conflicted with another operation.
429	Too Many Requests	You're making too many requests at once. Slow down!
500	Internal Server Error	We've got some problem with our service. Please try again later.
503	Service Unavailable	We're temporarily offline for maintenance. Please try again later.
504	Gateway Timeout	The deadline expired in which to perform the operation specified by your request.

important

When API errors occur, it is up to you to retry your request - BidZenith does not keep track of failed requests.

Versioning

The BidZenith API is versioned. A new API version is released when we introduce a backwards-incompatible change to the API. For example, changing a field type or name, or deprecating endpoints.

While we're adding functionality to our API, we won't release a new API version. You'll be able to take advantage of this non-breaking backwards-compatible changes directly on the API version you're currently using.

BidZenith considers the following changes to be backwards-compatible:

• Adding new API resources.

• Adding new optional request parameters to existing API methods.

• Adding new properties to existing API responses.

• Changing the order of properties in existing API responses.

• Changing the length or format of opaque strings such as object IDs, error messages, and other human-readable strings.

important

Your integration should gracefully handle backwards-compatible changes.

And that's basically it 🎉! Now you can go focus on your business while we monetize your data through auctions.