Skip to content

Web Service API

This document describes the Acclaim web service API, a REST service that allows organizations to manage their badges and issue badges on behalf of other organizations.

API Conventions

  • All requests must use SSL.
  • Authentication is handled via HTTP Basic Authentication as described below.
  • All requests must be in JSON format with Content-Type: application/json
  • Clients of the web service must accept JSON as response data.
  • All references to static assets (e.g. image_url in Get Badges response and photo_url in List Organization responses) are subject to change. These resource locations can always be found by calling the appropriate API.

API Versions

  • 1.0 is the current (and only) version.

Backwards Compatibility

We won't introduce backwards-incompatible changes to a specific version of the API. If backwards-incompatible changes are necessary to support new features, then a new version of the API will be introduced. When a new version is introduced, both the new version and the prior version will be supported simultaneously. The prior version of the API will eventually be deprecated and removed.

Backwards- compatible changes include:

  • Adding a new attribute to an existing object is backwards-compatible.
  • Adding a new API path is backwards-compatible.

Backwards- incompatible changes include:

  • Changing or removing an existing path name is backwards-incompatible.
  • Changing or removing an existing object name is backwards-incompatible.
  • Changing or removing an existing attribute name is backwards-incompatible.

URL Construction

Web service URLs are constructed as follows:

https://api.youracclaim.com/v1/<endpoint_path>

Authentication

You can authenticate with your personal user account, or you can authenticate as an organization.

  • User When you authenticate with your own Authorization Token, you have access to your own account profile, badges you've earned, and any organizations you're a member of.
  • Organization When you authenticate with an organization's Authorization Token, you only have access to that organization, its badge templates, and any badges it has issued.

Authentication is handled via HTTP Basic Authentication with the user's authorization_token as the username and a blank password. Every request requires HTTP Basic Authentication.

Example headers for a POST request:

Accept: application/json
Authorization: Basic SFRkYXVTanFYeWVzNUxieExPNUdadzo=
Content-Type: application/json
Content-Length: 42

Depending on what tool you're using to connect to the API, it may not be necessary to manually set any of these headers. For example, creating a badge template via the curl command line tool might look like this:

curl -u 'HTdauSjqXyes5LbxLO5GZw':'' \
  -F name="Fencing Club Champion" \
  -F description="The earner of this badge won the fencing club championship." \
  -F template_type="Skill" \
  https://example.com/api/v1/organizations/7d86d7c9-cf86-437b-9c10-1e2cc0df4491/badge_templates.json

As this example demonstrates, the Authorization header is created by using the authorization_token as the HTTP username, with a blank password. For example, if the user's authorization_token is HTdauSjqXyes5LbxLO5GZw, the Authorization header would be manually created like this:

  1. Create the standard username:password string with the authorization_token and a blank password: HTdauSjqXyes5LbxLO5GZw:.
  2. Base64 encode the username:password string: base64encode("HTdauSjqXyes5LbxLO5GZw:") = "OkhUZGF1U2pxWHllczVMYnhMTzVHWnc=".
  3. Create the complete Authorization header: Authorization: Basic OkhUZGF1U2pxWHllczVMYnhMTzVHWnc=.

Again, this process may be taken care of for your by whatever tool you are using, such as curl, a REST client library, etc.

The authorization_token grants full permission to the web service API on behalf of the user, so authorization_token should be treated with the same sensitivity as a password. Acclaim admins can see a user's authorization token by viewing the page for that user in the admin section.

Web Service Responses

Request Result Status Code Response Body
GET Success 200 (OK) The JSON resource
GET Not found 404 (Not Found) { message: "Resource not found." }
POST Success 201 (Created) The JSON resource with its URL in the Location header
PUT Success 200 (OK) The JSON resource
POST/PUT Missing required parameter 400 (Bad Request) { message: "Missing required parameter: email" }
POST/PUT Validation failed 422 (Unprocessable Entity) { message: "Email address is invalid" }
Any Unexpected error 500 (Internal Server Error) { message: "Oops. Something went wrong, but no details are available." }

Wrapped Responses

The web service wraps responses with the following format:

{
  data: {
    <response data>
  },
  metadata: {
    <response metadata>
  }
}

Only certain responses contain <response metadata>. It's used for returning relevant info for paged results. In particular, Badge Templates and Issued Badges responses are paged and include <response metadata>. Refer to the documentation for those endpoints for details.

Common Errors

If you get the response...

Response Then...
{ "message": "You need to sign in before continuing." } ...you need to specify the correct Authorization header.
{ "message": "You have to confirm your account before continuing." } ...you must confirm your account by responding to the confirmation email you received.
{ "message": "Your account is locked. Please contact us for assistance." } ...your account is locked.
{ "message": "Your account was not activated yet." } ...your account is disabled.

Validation Failures

The web service will validate data when creating and updating a resource. If validation fails, the server will return a 422 status code with a list of attributes that failed validation. The message value will contain a comma-separated list of validation errors, and an array of errors and their respective attribute names will also be included. For example:

{
  data: {
    "message": "Validation failed: Email can't be blank, ...",
    "errors": [
      {
        "attribute": "email",
        "messages": [
          "can't be blank",
          ...
        ]
      },
      ...
    ]
  }
}