RESTFul APIs

Nitro is a set of APIs that can be accessed via any programming language supporting HTTPS protocol. These API calls are used to leverage all the capabilities of the Nitro platform such as logging actions, generating leaderboards, crediting and debiting points, user manipulation, and more.

Note: All APIs require UTF-8 encoding when sending data to Nitro.

RESTFul APIs use the API Gateway to authenticate requests. They authenticate using OAuth and JWT tokens and support modern REST standards around headers and structure.

Sample Code
Copy `curl -X POST "https://api.bunchball.com/groups/123/users/67" -H "accept: application/json" -H "authorization: Bearer <access_token>" -H "Content-Type: application/json" -d "{}"`

API Documentation

RESTFul APIs are documented via an auto-generated framework (Swagger) that provides direct access to the API Gateway where you can view and test APIs. For the list of available APIs in production and sandbox, visit:

Production - https://api.bunchball.com/docs
Sandbox - https://api.sandbox.bunchball.com/docs

The following APIs are not documented on the API documentation site.

Run an API

Each method on the API site is expandable. Click the API name to view the API's description and its parameters.

Open Nitro Studio > Tools > API Documentation. You are automatically authorized on the RESTFul API site for that environment.
- Sandbox - https://api.sandbox.bunchball.com/docs
- Production - https://api.bunchball.com/docs
Click the name of the API you want to run.
Click Try it out ().
Enter the parameters and click Execute.

The request and response are generated.

Error Handling

It's important to implement robust error handling when using Nitro APIs to ensure reliability and resolution of issues. Errors should log with sufficient detail for troubleshooting and alert your team to any errors that occur.

Status Codes

When working with APIs, the following status codes may be returned:

200 - Successful response.
400 - Bad request. Typically returned when the parameters sent were invalid, you have invalid JSON, or something similar.
401 - Unauthorized. Typically an invalid or missing token.
403 - Forbidden. Typically returned with an award account if verification is required and a user is not verified. May also be returned with whitelisting.
404 - Resource not found. Typically returned when requesting a specific ID and often when a user is not found.
500 - Server error in Nitro. Best practice is to set up an alert that sends the error into logs to determine what is wrong with the data and why it wasn't seen by Nitro.
503 - Service Unavailable. Typically timeouts or service gateway issues (not a Nitro server issue).