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 tokens and support modern REST standards around headers and structure.

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 the 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.

• admin.backupSiteConfig
• admin.restoreSiteConfig
• Traditional APIs - Nitro's traditional API documentation is available in PDF format. Traditional APIs should only be used when a REST version is unavailable.

Run an API

To run a method that supports OAuth security, you must:

1. Create an OAuth Client with a scope appropriate for that method. Or, use a global scope to allow reading and writing all available resources through the API.
2. Use the Client Id and Secret Key to generate an OAuth token.
3. Use the OAuth access token to call the API gateway endpoint at https://api.sandbox.bunchball.com or https://api.bunchball.com.

Test an API

Each method on the API site is expandable. Click the API name to view the API's description and its parameters. Once you define authorization, you can use "Try it out" to add parameters and run the API.

1. Create an OAuth Client to be used for testing APIs. This should not be the same client in use for your production environment.

2. Access the RESTFul API site at:
   • Sandbox - https://api.sandbox.bunchball.com/docs
   • Production - https://api.bunchball.com/docs
3. Click Authorize () to create a token for use in testing the APIs.
4. Enter the client_id and client_secret from the OAuth Client created in step 1, and click Execute.
   If the page results in an error, verify the OAuth Client was created for the environment where you are testing. For example, you cannot test in sandbox with a production OAuth Client.
5. Click the name of the API you want to run.
6. Click Try it out ().
7. Enter the parameters and click Execute.

The request and response are generated.

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 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 (such as /challenges/{challengeId}), not when doing a search and the result is empty (e.g. /challenges?search=user-doesn't-exist returns a successful, empty 200 response).

• 500 - Server error in Nitro.

• 503 - Typically timeouts or service gateway issues (not a Nitro server issue).

See also

Web components

Create a custom web component