UserBadges

Documentation

The following documents the UserBadges.com API, which is used to interact with the UserBadges system to query and create users and badges for your service.

Main Concepts

There are a few concepts that you should understand before beginning to use the UserBadges.com service.

What is a Service?

A service is something that you register on UserBadges.com to get a unique secret API key so that you can create badges and users. For example, you might run a cooking site with the service name of topchefs. You could have the following users and badges to show that someone has contributed recipes, give awards based on the number of contributed recipes and the number of categories their recipes cover, and whether the user's recipes are frequently made by others:

What is a Badge?

A badge is an object that can be awarded to a user. For example, when a user posts 25 comments you could award them a commenter badge. Badges generally have a name and custom fields which you define. Several custom fields have special meanings if you set them:

Others are generated and managed on the server, such as a count of total times the badge was assigned and latest date the badge was assigned.

Badges must be registered with a service before they can be assigned to users.

The example commenter badge might look like this:

Example Badge

{
    "count": 1,
    "description": "Posted at least 25 comments",
    "date": "2013-02-23T16:41:37.084Z",
    "link": "/badges/commenter",
    "name": "commenter"
}

What is a User?

A user is an object that can have badges awarded. Each user has a name, a list of badges which she can have awarded multiple times, a count for each badge which stores the number of times each badge was awarded, and a latest date each badge was awarded. For example:

Example user

{
    "badges": [
        {
            "count": 2,
            "latest": "2013-02-24T19:16:15.141Z",
            "name": "donated"
        },
        {
            "count": 1,
            "latest": "2013-02-24T19:16:15.141Z",
            "name": "test"
        }
    ], 
    "latest": "2013-02-24T19:16:15.141Z",
    "name": "bob"
}

Displaying User Badges

There are two ways that you can display user badges on your website. The simplest is to include our javascript on your page and markup certain elements to get asynchronously populated with badges on page load. This gives you a good amount of flexibility and is extremely easy to set up. The second way to display user badges is to use one of the client libraries or raw API calls below on your server to get a list of badges, then render them into your HTML templates.

Simple Badge Display

To use the simpler method, you must use jQuery on your website, along with special tags. You can inclue the UserBadges.com javascript and style like so:

Code Example

<link href="http://www.userbadges.com/themes/stackoverflow.css" rel="stylesheet" type="text/css"/>
<script src="http://www.userbadges.com/userbadges.js"></script>

Then, simply define one or more elements to be populated with badges:

Code Example

<span class="userbadges" data-service="demo" data-user="daniel"></span>

When the page loads, these elements will be replaced with badges fetched via AJAX calls to the UserBadges.com API. The resulting modified HTML will look something like this:

Code Example

<span class="userbadges" data-service="demo" data-user="daniel">
    <span class="userbadge donated">
        <a href="/badges/donated">
            <span class="name" title="Donated at least $5">
                donated
            </span>
        </a>
        <span class="count">
            x2
        </span>
    </span>
    <span class="userbadge popular">
        <a href="/badges/popular">
            <span class="name" title="Post has at least 100 views">
                popular
            </span>
        </a>
    </span>
    <span class="userbadge test1" title="">test1</span>
</span>

Which will render out using the stackoverflow.css theme as:

Themes

The following themes are available:

Controlling Rendering

You can control how badges are rendered on the page by overriding the UserBadges.renderBadge method before the page finishes loading. For example, if you wanted badges to be a plain text list:

Code Example

<ul class="userbadges" data-service="demo" data-user="daniel"></ul>
<script type="text/javascript">
UserBadges.renderBadge = function (badge) {
    return '<li><span class="userbadge">' + badge.name + '</span></li>'
};
</script>

The badge object passed to the UserBadges.renderBadge function looks like the following and contains any custom fields you have set for the badge. The globalCount field is the total number of times this badge has been assigned for all users, and globalLatest is the latest time this badge was assigned to any user.

Badge Object Example

{
    "name": "commenter",
    "description": "Commented on at least 5 posts",
    "count": 1,
    "latest": "",
    "globalCount": 25,
    "globalLatest": "",
    ...
}

API Client Libraries

Several backend client libraries are available to make integrating with the UserBadges.com API simpler:

Examples

Examples below are given in the following forms:

Content Types

Requests and responses use JSON to encode data. This means that your requests that send data (e.g. HTTP PUT/POST requests) should send the following content type header:

HTTP Request Required Headers

Content-Type: application/json

Authentication & Authorization

Calls to the API that modify data must be authenticated. Each service is given an API key which is to be transmitted as an HTTP Authorization header using HTTPS (a securely encrypted HTTP channel). This key is used to ensure that payloads originate from a valid secred-holding application, and HTTPS is used to ensure that the request cannot be read or modified in transit.

Each service is authorized to modify its own badges and users. Using the wrong API key or wrong service name will result in access being denied to the requested resources.

For example, if your secret key (found in your account settings) is abc123:

Example Authorized Request

PUT https://userbadges.com/v1/demo/users/daniel.json HTTP/1.1
Authorization: abc123
Content-Type: application/json

{
    "badges": [
        "test1",
        "test2"
    ]
}

HTTPie example

http put https://userbadges.com/v1/demo/users/daniel.json Authorization:abc123 badges:='["test1", "test2"]'

cURL example

curl -X PUT https://userbadges.com/v1/demo/users/daniel.json -H 'Authorization: abc123' -H 'Content-Type: application/json' -d '{"badges":["test1", "test2"]}'

Note: Authentication can be bypassed if you use a service name of test. This bypass is provided to make testing UserBadges.com simpler from the commandline, allowing you to ignore authentication.

Badges

Get Service Badges

Get a list of badges registered with a particular service. Custom fields are returned in each badge object.

Request Parameters

service The name of the service to query, e.g. test
sort (optional) Sort the responses: name, -name, count, -count, date, -date

Request

GET https://userbadges.com/v1/:service/badges.json?sort=:sort HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Response-Time: 1ms

{
    "badges": [
        {
            "count": 5, 
            "description": "User donated to site", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "name": "donated", 
            "type": "gold"
        }, 
        {
            "count": 4, 
            "description": "Another test badge", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "name": "test", 
            "type": "silver"
        }
    ]
}
HTTP Error Codes

400 Badly formed request, e.g. invalid sort method
404 Service was not found
500 Internal server error during query

Adding or Modifying Service Badges

Add or modify badges for a particular service. Badges that do not exist are created automatically. Each badge must have a name property; all others are optional. Custom fields are allowed, and the example below uses several (description, link, and myCustomField).

Request Parameters

badges The badges to add as JSON
service The name of the service to query, e.g. test
signature The signature of the request, e.g. a1e4f33efa89af62351ec7582ca97f1f592541bb
ts The timestamp of the request, e.g. 1361151319

Request

PUT https://userbadges.com/v1/:service/badges.json?ts=:ts&signature=:signature HTTP/1.1
Content-Type: application/json

{
    "badges": [
        {
            "name": "test",
            "description": "This is a test badge",
            "link": "/badges/test",
            "myCustomField": 5
        }
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Response-Time: 1ms

{
    "badges": [
        {
            "count": 5, 
            "description": "User donated to site", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "name": "donated", 
            "type": "gold"
        }, 
        {
            "count": 4, 
            "description": "This is a test badge", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "name": "test", 
            "myCustomField": 5
        }
    ]
}
HTTP Error Codes

400 Badly formed request, e.g. missing signature
401 Unauthorized, e.g. invalid signature
404 Service not found
500 Internal server error during query

Deleting Service Badges

Delete one or more badges from a particular service. Removing a badge from a service will also remove it from all users of that service. A list of remaining badges will be returned from this call.

Request Parameters

badges The badges to add as JSON
service The name of the service to query, e.g. test
signature The signature of the request, e.g. a1e4f33efa89af62351ec7582ca97f1f592541bb
ts The timestamp of the request, e.g. 1361151319

Request

DELETE https://userbadges.com/v1/:service/badges.json?ts=:ts&signature=:signature HTTP/1.1
Content-Type: application/json

{
    "badges": [
        "test"
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Response-Time: 1ms

{
    "badges": [
        {
            "count": 5, 
            "description": "User donated to site", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "name": "donated", 
            "type": "gold"
        }
    ]
}
HTTP Error Codes

400 Badly formed request, e.g. missing signature
401 Unauthorized, e.g. invalid signature
404 Service not found
500 Internal server error during query

Users

Get Users

Get a list of users and the badges each user has been awarded. The returned data structure contains a list of badges including custom fields and total counts / latest dates across all users as well as a list of users that reference these badges along with a count number of times the badge was awarded to that specific user and latest date that badge was awarded to that specific user.

Request Parameters

names (optional) The names of users to query, seperated by commas, e.g. user1,user2,user3
service The name of the service to query, e.g. test
sort (optional) Sort the responses: name, -name, count, -count, date, -date

Request

GET https://userbadges.com/v1/:service/users.json?names=:names&sort=:sort HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Response-Time: 2ms

{
    "badges": {
        "donated": {
            "count": 5, 
            "description": "User donated to site", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "type": "gold"
        }, 
        "test": {
            "count": 4, 
            "description": "Another test badge", 
            "latest": "2013-02-24T19:16:15.142Z", 
            "type": "silver"
        }
    }, 
    "users": [
        {
            "badges": [
                {
                    "count": 4, 
                    "latest": "2013-02-24T19:16:15.141Z", 
                    "name": "donated"
                }, 
                {
                    "count": 4, 
                    "latest": "2013-02-24T19:16:15.141Z", 
                    "name": "test"
                }
            ], 
            "latest": "2013-02-24T19:16:15.141Z", 
            "name": "bob"
        }, 
        {
            "badges": [
                {
                    "count": 3, 
                    "latest": "2013-02-23T16:41:37.084Z", 
                    "name": "donated"
                }
            ], 
            "latest": "2013-02-23T16:41:37.084Z", 
            "name": "daniel"
        }
    ]
}
HTTP Error Codes

400 Badly formed request, e.g. invalid sort method
404 Service not found
500 Internal server error during query

Award Badges to a User

Award badges to a specific user by badge name. The list of all badges assigned to the user after the update are returned along with the affected user name.

Request Parameters

badges The badges to add as JSON
name The name of the user to award badges, e.g. daniel
service The name of the service to query, e.g. test
signature The signature of the request, e.g. a1e4f33efa89af62351ec7582ca97f1f592541bb
ts The timestamp of the request, e.g. 1361151319

Request

PUT https://userbadges.com/v1/:service/users/:name.json?ts=:ts&signature=:signature HTTP/1.1
Content-Type: application/json

{
    "badges": [
        "commenter",
        "popular",
        ...
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Response-Time: 5ms

{
    "user": {
        "badges": [
            "commenter",
            "popular",
            ...
        ], 
        "name": "daniel"
    }
}
HTTP Error Codes

400 Badly formed request, e.g. missing signature
401 Unauthorized, e.g. invalid signature
404 Service not found
500 Internal server error during query

Remove Badges from a User

Remove badges from a specific user by badge name. The list of all badges assigned to the user after the update are returned along with the affected user name.

Request Parameters

badges The badges to remove as JSON
name The name of the user to award badges, e.g. daniel
service The name of the service to query, e.g. test
signature The signature of the request, e.g. a1e4f33efa89af62351ec7582ca97f1f592541bb
ts The timestamp of the request, e.g. 1361151319

Request

DELETE https://userbadges.com/v1/:service/users/:name.json?ts=:ts&signature=:signature HTTP/1.1
Content-Type: application/json

{
    "badges": [
        "commenter",
        ...
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Response-Time: 3ms

{
    "user": {
        "badges": [
            "popular",
            ...
        ], 
        "name": "daniel"
    }
}
HTTP Error Codes

400 Badly formed request, e.g. missing signature
401 Unauthorized, e.g. invalid signature
404 Service not found
500 Internal server error during query