NAV
curl Ruby

Introduction

API Endpoint

https://badgeapi.lancaster.ac.uk/v1/

Welcome to the Lancaster University Badge API! You can use our API to access Badge API endpoints, which can get information on the Lancaster University Gamification platform developed by the Innovation Hub.

The Badge API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website’s client-side code). JSON will be returned in all responses from the API, including errors.

Using the Badge API, you can display badges, create new badges and collections, manage these and issue badges to a recipient.

We have bindings in curl & Ruby. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the buttons in the top right.

Ruby Gem

If you are using Ruby or Ruby on Rails you can utilise our gem to interact with the API easily.

The gem is available through Ruby gems and the repository can be found here innovationhublancaster/badgeapi with further documentation on how to install it.

Using the Ruby tab on the left-hand side will show examples how how to interact with the API using the gem.

Authentication

Example Request

$ curl https://badgeapi.lancaster.ac.uk/v1/badges -H "Authorization: Token token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# curl uses -H/--header to allow the inclusion of an extra header

require "badgeapi"
Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Badgeapi.ssl_ca_cert = "path/to/ca/cert" #Certificate Authority (CA) certificates bundle

# For the gem to work with the required https, it needs to know the location of a Certificate Authority (CA) certificates bundle and this needs to be set with Badgeapi.ssl_ca_cert. This guide can help you in finding the CA on your system https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates.

# I have a nice way of getting this working locally, if you want to know more email t.skarbek-wazynski@lancaster.ac.uk.


You must replace XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your personal 32 digit API key.

You authenticate to the Badges API by providing your API Key

To authenticate with the Badge API a personal API keys is required to allow access. You can register a new Badge API key by emailing the Innovation Hub.

The Badge API expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

All API requests must be made over HTTPS. TODO: Calls made over plain HTTP will fail. You must authenticate for all requests.

Errors

Example of response to bad request i.e incorrect api key

    $ curl https://badgeapi.lancaster.ac.uk/badges.json -IH
      "Authorization: Token token=incorrectapikey"

    HTTP/1.1 401 Unauthorized
    Content-Type: application/json; charset=utf-8
    Connection: close



    $ curl https://badgeapi.lancaster.ac.uk/badges -H "Authorization: Token token=incorrectapikey"

    {
        "error": {
            "type":"invalid_request_error",
            "message":"The API key is missing or invalid",
            "status":401
        }
    }

    require "badgeapi"
    Badgeapi.api_key = "incorrectapikey"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.find("book-worm")

    Invalid Request Error

    ###########################################################
    # The Ruby gem will raise two types of exception:

    # When a request to the API is invalid this is returned
    # with a message explaining the issue.
    InvalidRequestError

    # When the API cannot respond due to a server issue or
    # lost call this is raised
    ApiError

    # Each Exception has a message and http_status and a json_body

The Badge API uses conventional HTTP response codes to indicate success or failure of an API request. We also return a JSON object with more detailed explanations of the issue. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with our servers. Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully, we return a 402 error code.

Status Codes

Code Meaning
200
OK
Everything worked as expected.
400
Bad Request
Your request was bad
401
Unauthorized
Your API key is wrong
403
Forbidden
Your access level is insufficient
404
Not Found
The specified could not be found
405
Method Not Allowed
You tried to access an invalid method
406
Not Acceptable
You requested a format that isn’t json
410
Gone
The object requested has been removed from our servers
429
Too Many Requests
You’re making too many requests
500
Internal Server Error
We had a problem with our server. Try again later.
503
Service Unavailable
We’re temporarily offline for maintenance. Please try again later.

Error Types

Error Meaning
invalid_request_error
Invalid request errors as raised when the submitted request is invalid
api_error
When the API cannot process the request due to a fault. Should appear very infrequently.

Handling errors

Our API libraries can raise exceptions for many reasons. We recommend always trying to gracefully handle exceptions from our API.

    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    # No badge with id: "not-a-badge"
    begin
        badge = Badgeapi::Badge.find("not-a-badge")
    rescue InvalidRequestError => e
        puts e.message
        # This is where the flow of code above will end
        # Something was wrong with the request
        # Handle exception in some way
    rescue ApiError => e
        puts e.message
        # Service is unavailable
        # Try request again later.
    rescue Exception => e
        puts e.message
        # Something else is wrong
    end

Expanding Objects

    GET https://badgeapi.lancaster.ac.uk/v1/badges?{EXPAND_PARAM}
    badge = Badgeapi::Badge.all {HASH OF PARAMS}

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges?expand=collection
    -H "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.all expand: "collection"

Example response

    [
        {
            "id":"book-worm",
            "name":"Book Worm",
            "description":"Description?",
            "requirements":"Loan out 25 books",
            "hint":"You must like books...",
            "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                book-worm/badge.png",
            "collection_id":"library",
            "level":"bronze",
            "points":"25",
            "auto_issue":"false",
            "object":"badge",
            "status":"live",
            "created_at":"2015-03-25T13:28:44.161Z",
            "updated_at":"2015-03-25T13:28:44.161Z",
            "collection": {
                "id": "library",
                "name": "Library",
                "description": "All of the badges available
                                related to library data",
                "total_points_available":"125",
                "badge_count":"4",
                "object":"collection",
                "created_at": "2015-03-31T14:07:13.505Z",
                "updated_at": "2015-03-31T15:05:42.955Z"
            }
        },
        {"...":"..."},
        {"...":"..."},
        {"...":"..."}
    ]

Many objects in the Badges API contain the id of another related objects in their response properties. Those objects can be expanded inline with the inclusion of a expand request parameter. Objects that can be expanded are noted in this documentation. You can expand multiple things by sending a comma separated list of the objects with the param.

Badges

Badges are a form of recognition for completing a task or goal. With the API you can create, edit and destroy badges as well as issuing and revoking badges to user who have earned them.

The badges object

Example response

    {
        "id":"book-worm",
        "name":"Book Worm",
        "description":"You loaned out 25 books!",
        "requirements":"Loan out 25 books",
        "required_badges":[],
        "hint":"You must like books...",
        "image":"https://badgeapi.lancaster.ac.uk/badge_images/
            book-worm/badge.png",
        "collection_id":"library",
        "level":"bronze",
        "points":"25",
        "auto_issue":"false",
        "object":"badge",
        "status":"live",
        "created_at":"2015-03-25T13:28:44.161Z",
        "updated_at":"2015-03-25T13:28:44.161Z"
    }
Attributes Information
id
string
The unique id of the badge
name
string
Name of the badge must be unique
description
text
The message displayed to the user after a badge is earned should describe what they had to do to earn it. e.g “You loaned out 25 books!”
requirements
text
What is required to earn the badge
required_badges
Array
What other badges are required to be issued before this badge can be successfully issued
hint
text
A hint displayed to potential earners suggesting how they could earn the badge
image
string
The url of the generated badge image
collection_id
string
The id the the collection the badge belongs to
level
string
The level of the badge, can be bronze, silver, gold, platinum. The level represents the difficulty required to achieve the badge.
points
string
How many points the badge is worth, this is directly tied to level. Bronze: 25, Silver: 50, Gold: 75, Platinum: 100.
auto_issue
boolean
Should the badge auto issue if all required badges earned. Can only be true for Silver, Gold and Platinum badges.
status
string
Can either be live or draft. Live should be available to for recipients to see. Draft should be hidden from recipients.
object
string
What object the JSON represents.
created_at
datetime
The time and date of when a badge was first created
updated_at
datetime
The time and date of the last update to the badge

Required Badges

Some badges require other badges are earned before it can be successfully issued to a user. If these have not be earn’t any attempt to issue the bade with these requirements will fail only after all the required badges have been issue will this badge be able to be sucessfully issued.

Create a badge

Definition

    POST https://badgeapi.lancaster.ac.uk/v1/badges
    badge = Badgeapi::Badge.create

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges
    -H "Authorization:  Token token=
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "badge" : {
            "name" : "New Badge",
            "description" : "You loved the Badge API",
            "requirements" : "You need to love the Badge API",
            "hint" : "Love us..",
            "level" : "bronze",
            "status":"live",
            "collection_id" : "library"
        }}'
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.create(
        name: "New Badge",
        description: "You loved the Badge API",
        requirements: "You need to love the Badge API",
        hint: "Love us..",
        level: "bronze",
        status: "live",
        collection_id: "library"
    )

Example response

    {
        "id":"new-badge",
        "name" : "New Badge",
        "description" : "You loved the Badge API",
        "requirements" : "You need to love the Badge API",
        "required_badges":[],
        "hint" :"Love us..",
        "image":"https://badgeapi.lancaster.ac.uk/badge_images/
            new-badge/badge.png",
        "collection_id":"library",
        "level":"bronze",
        "points":"25",
        "auto_issue":"false",
        "object":"badge",
        "status":"live",
        "created_at":"2015-03-25T13:28:44.161Z",
        "updated_at":"2015-03-25T13:28:44.161Z"
    }

Badges can be created via the api by posting a JSON object of the required fields to the API. After creating a badge you can set any required badges via the required API calls Required Badges.

Badge images are auto generated by the api using the name and level to determine the design.

Arguments Information
name (string)
REQUIRED
Name of the badge must be unique
description (text)
REQUIRED
The message displayed to the user after a badge is earned should describe what they had to do to earn it. e.g “You loaned out 25 books!”
requirements (text)
REQUIRED
What is required to earn the badge
hint (text)
REQUIRED
A hint displayed to potential earners suggesting how they could earn the badge
collection_id (string)
REQUIRED
The id the the collection the badge belongs to
level (string)
REQUIRED
The level of difficulty required to achieve the badge. Must be either: “bronze”, “silver”, “gold” or “platinum”.
auto_issue (boolean)
Should the badge be auto issued if all required badges are earned. Can only be used on “silver”, “gold” or “platinum” level badges.
status
string
Can either be live or draft. Live should be available to for recipients to see. Draft should be hidden from recipients.

Returns

Returns the created collection object if call succeeded. The returned object contains all the information about the collection.

Required badges

Definition

    POST https://badgeapi.lancaster.ac.uk/v1/badges/{BADGE_ID}/requires
    DELETE https://badgeapi.lancaster.ac.uk/v1/badges/{BADGE_ID}/requires
    badge = Badgeapi::Badge.add_badge_requirement({BADGE_ID}, {REQUIRED_BADGE_ID})

    badge = Badgeapi::Badge.remove_badge_requirement({BADGE_ID}, {REQUIRED_BADGE_ID})

Example request

    # Create Requirement
    curl https://badgeapi.lancaster.ac.uk/v1/badges/mega-book-worm/requires
    -H "Authorization: Token token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "required_badge": {
            "id":"book-worm"
        }}'

    # Destroy Requirement
    curl https://badgeapi.lancaster.ac.uk/v1/badges/mega-book-worm/requires
    -H "Authorization: Token token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "required_badge": {
            "id":"book-worm"
        }}'
    -X DELETE
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    # Create Requirement
    badge = Badgeapi::Badge.add_badge_requirement("mega-book-worm", "book-worm")


    # Destroy Requirement
    badge = Badgeapi::Badge.remove_badge_requirement("mega-book-worm", "book-worm")

Example response

     {
        "id":"mega-book-worm",
        "name":"Mega Book Worm",
        "description":"You loaned out 50 books",
        "requirements":"Loan out 50 books",
        "hint":"You must really like books...",
        "image":"https://badgeapi.lancaster.ac.uk/badge_images/
            mega-book-worm/badge.png",
        "collection_id":"library",
        "created_at":"2015-06-01T09:41:54.648Z",
        "updated_at":"2015-06-01T09:41:54.648Z",
        "level":"bronze",
        "points":"25",
        "auto_issue":"false",
        "object":"badge",
        "status":"live",
        "required_badges":[
            {
                "id":"book-worm",
                "name":"Book Worm",
                "description":"You loaned out 25 books",
                "requirements":"Loan out 25 books",
                "hint":"You must like books...",
                "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                    book-worm/badge.png",
                "collection_id":"library",
                "created_at":"2015-06-01T09:41:54.572Z",
                "updated_at":"2015-06-01T09:41:54.572Z",
                "required_badges":[],
                "level":"bronze",
                "points":"25",
                "auto_issue":"false",
                "object":"badge",
                "status":"live"
            }
        ]
     }                                                                                                                                                                              

Badges can require other badges to be issued before that badge can be issued. You can add and remove required badges through a call to the API passing in the id of the badge to be required.

Only one badge can be made to be required at a time, if a badge needs multiple required badges then this API call needs to be made for each of those required badges.

Arguments Information
id (string)
REQUIRED
The id of theparent badge
required_badge_id (string)
REQUIRED
The id of required badge

Returns

Returns the updated badge with a list of the amended required badges.

Retrieve a badge

Definition

    GET https://badgeapi.lancaster.ac.uk/v1/badges/{BADGE_ID}
    badge = Badgeapi::Badge.find({BADGE_ID})

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges/book-worm -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.find("book-worm")

    badge.name #=> "Book Worm"

Example response

    {
        "id":"book-worm",
        "name":"Book Worm",
        "description":"Description?",
        "requirements":"Loan out 25 books",
        "required_badges":[],
        "hint":"You must like books...",
        "image":"https://badgeapi.lancaster.ac.uk/badge_images/
            book-worm/badge.png",
        "collection_id":"library",
        "level":"bronze",
        "points":"25",
        "auto_issue":"false",
        "object":"badge",
        "status":"live",
        "created_at":"2015-03-25T13:28:44.161Z",
        "updated_at":"2015-03-25T13:28:44.161Z"
    }

You can retrieve a single badges details by specifying the id of the badge you wish to retrieve

Arguments Information
id (string)
REQUIRED
The id of the badge to be retrieved.
expand (string)
OPTIONAL
Comma separated list to expand object. Valid values: collection

Returns

Returns the badge object

Update a badge

Definition

    PATCH/PUT https://badgeapi.lancaster.ac.uk/v1/badges/{BADGE_ID}
    badge = Badgeapi::Badge.find({BADGE_ID})
    badge.name = {NEW_BADGE_NAME}
    ...
    badge.save

    # ALTERNATIVELY

    Badgeapi::Badge.update({BADGE_ID}, {PARAMETER}, {PARAMETER} ...)

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges/book-worm -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "badge" : {
                "name" : "Book Worm Updated"
    }}'
    --request PATCH
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.find("book-worm")
    badge.name = "Book Worm Updated"
    badge.save

    # ALTERNATIVELY

    Badgeapi::Badge.update("book-worm",
        name: "Book Worm Updated",
        description: "Updated Description"
    )

Example response

Note: The original id: book-worm will still work for interacting with this badge

    {
        "id":"book-worm-updated",
        "name":"Book Worm Updated",
        "description":"Updated Description",
        "requirements":"Loan out 25 books",
        "required_badges":[],
        "hint":"You must like books...",
        "image":"https://badgeapi.lancaster.ac.uk/badge_images/
            book-worm-updated/badge.png",
        "collection_id":"library",
        "level":"bronze",
        "points":"25",
        "auto_issue":"false",
        "object":"badge",
        "status":"live",
        "created_at":"2015-03-25T13:28:44.161Z",
        "updated_at":"2015-03-30T13:00:44.161Z"
    }

Updates the specified badge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments Information
name (string)
OPTIONAL
Name of the badge must be unique
description (text)
OPTIONAL
The message displayed to the user after a badge is earned should describe what they had to do to earn it. e.g “You loaned out 25 books!”
requirements (text)
OPTIONAL
What is required to earn the badge
hint (text)
OPTIONAL
A hint displayed to potential earners suggesting how they could earn the badge
collection_id (string)
OPTIONAL
The id the the collection the badge belongs to.
level (string)
OPTIONAL
The level of difficulty required to achieve the badge. Must be either: “bronze”, “silver”, “gold” or “platinum”.
auto_issue (boolean)<
Should the badge be auto issued if all required badges are earned. Can only be used on “silver”, “gold” or “platinum” level badges.

Returns

Returns the badge object if the update succeeded. Raises an error if update parameters are invalid.

Delete a badge

    DELETE https://badgeapi.lancaster.ac.uk/v1/badges/{BADGE_ID}
    badge = Badgeapi::Badge.destroy({BADGE_ID})

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges/book-worm -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -X DELETE
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.destroy("book-worm")

Example response

    {
        "id":"book-worm",
        "name":"Book Worm",
        "description":"You loaned out 25 books!",
        "requirements":"Loan out 25 books",
        "required_badges":[],
        "hint":"You must like books...",
        "image":"https://badgeapi.lancaster.ac.uk/badge_images/
            book-worm/badge.png",
        "collection_id":"library",
        "auto_issue":"false",
        "object":"badge",
        "status":"live",
        "created_at":"2015-03-25T13:28:44.161Z",
        "updated_at":"2015-03-25T13:28:44.161Z"
    }

Permanently deletes a badge. It cannot be undone. Also immediately removes the badge from any earners backpack.

Arguments Information
id (string)
REQUIRED
The id of the badge to be deleted.

Returns

Returns the deleted badge. If the badge does not exist returns an error.

List all badges

Definition

    GET https://badgeapi.lancaster.ac.uk/v1/badges

    GET https://badgeapi.lancaster.ac.uk/v1/badges?{PARAMS}
    badge = Badgeapi::Badge.all

    badge = Badgeapi::Badge.all {HASH OF PARAMS}

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

    curl https://badgeapi.lancaster.ac.uk/v1/badges?collection_id=1 -H
        "Authorization: Token
        token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.all

    badge = Badgeapi::Badge.all collection_id: "library", limit: 1, expand: "collection"

Example response

    [
        {
            "id":"book-worm",
            "name":"Book Worm",
            "description":"You loaned out 25 books!",
            "requirements":"Loan out 25 books",
            "required_badges":[],
            "hint":"You must like books...",
            "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                book-worm/badge.png",
            "collection_id":"library",
            "level":"bronze",
            "points":"25",
            "auto_issue":"false",
            "object":"badge",
            "status":"live",
            "created_at":"2015-03-25T13:28:44.161Z",
            "updated_at":"2015-03-25T13:28:44.161Z"
        },
        {"...":"..."},
        {"...":"..."},
        {"...":"..."}
    ]

You can retrieve a complete list of all available badges via the API. You can also limit this to a list of all badges in the collection by specifying a collection id as a parameter or all the badges earned by a user.

Arguments Information
user (string)
OPTIONAL
Either the university email address or university card number of the recipient.
collection_id (string)
OPTIONAL
The id of the collection for the badges you want to retrieve.
limit (int)
OPTIONAL
Limit the number of badges retrieved.
expand (string)
OPTIONAL
Comma separated list to expand object. Valid values: collection

Returns

Returns a array of all available badges

Issuing a badge

Definition

    POST https://badgeapi.lancaster.ac.uk/v1/badges/{ID}/
        issue?recipient={RECIPIENT}
    badge = Badgeapi::Badge.issue({BADGE ID}, recipient: {RECIPIENT})

Example request using university email

    curl https://badgeapi.lancaster.ac.uk/v1/badges/book-worm/issue
    -H "Authorization:  Token token=
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "recipient" : "j.blogs@lancaster.ac.uk" }'
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.issue("book-worm",
        recipient: "j.blogs@lancaster.ac.uk"
    )

Example request using university card

    curl https://badgeapi.lancaster.ac.uk/v1/badges/book-worm/issue
    -H "Authorization:  Token token=
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "recipient" : "1234567" }'
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.issue("book-worm",
        recipient: "1234567"
    )

Example response

    {
        "total_score":"75",
        "badges_total":"2",
        "bronze_count":"1",
        "silver_count":"1",
        "gold_count":"0",
        "platinum_count":"0",
        "object":"recipient",
        "badges": [
            {
                "id":"book-worm",
                "name":"Book Worm",
                "description":"Description?",
                "requirements":"Loan out 25 books",
                "hint":"You must like books...",
                "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                    book-worm/badge.png",
                "collection_id":"library",
                "level":"bronze",
                "points":"25",
                "auto_issue":"false",
                "object":"badge",
                "status":"live",
                "issued_at":"2015-07-16T09:21:22.849Z",
                "created_at":"2015-03-25T13:28:44.161Z",
                "updated_at":"2015-03-25T13:28:44.161Z"
            },
            {"...":"..."}
        ]
    }

Badge issuing is a push event. In your system you should check a user (know as a recipient in the API) has met the requirements of the badge outlined in the description, if this is the case you can then issue the badge by posting a request to the API with the some details about badge and the recipient that is is to be issued to.

If a badge requires that other badges are issued before this badge can be issued the API will check this before issuing and return an error if the recipient is missing any required badges

A badge can only be issued to a recipient once, the API will return an error if the user is already a recipient of the badge you are trying to issue.

You can provide the recipient through three forms of identification, their university email address, their university card number or their username. If the API can find a user using the data provided it will issue the badge, however if a user cannot be found an error will be returned explaining the problem.

Arguments Information
recipient (string)
REQUIRED
Either the university email address, university card number of the recipient or username.

Returns

Returns a updated recipient

Revoking a badge

Definition

    POST https://badgeapi.lancaster.ac.uk/v1/badges/{ID}/
         revoke?recipient={RECIPIENT}
    badge = Badgeapi::Badge.revoke({BADGE ID}, recipient: {RECIPIENT})

Example request using university email

    curl https://badgeapi.lancaster.ac.uk/v1/badges/mega-book-worm/revoke
    -H "Authorization:  Token token=
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "recipient" : "j.blogs@lancaster.ac.uk" }'
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.revoke("mega-book-worm",
        recipient: "j.blogs@lancaster.ac.uk"
    )

Example request using university card number

    curl https://badgeapi.lancaster.ac.uk/v1/badges/mega-book-worm/revoke
    -H "Authorization:  Token token=
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "recipient" : "1234567" }'
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    badge = Badgeapi::Badge.revoke("mega-book-worm",
        recipient: "1234567"
    )

Example response

    {
        "total_score":"25",
        "badges_total":"1",
        "bronze_count":"1",
        "silver_count":"0",
        "gold_count":"0",
        "platinum_count":"0",
        "object":"recipient",
        "badges": [
            {
                "id":"book-worm",
                "name":"Book Worm",
                "description":"Description?",
                "requirements":"Loan out 25 books",
                "hint":"You must like books...",
                "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                    book-worm/badge.png",
                "collection_id":"library",
                "level":"bronze",
                "points":"25",
                "auto_issue":"false",
                "object":"badge",
                "status":"live",
                "issued_at":"2015-07-16T09:21:22.849Z",
                "created_at":"2015-03-25T13:28:44.161Z",
                "updated_at":"2015-03-25T13:28:44.161Z"
            },
        ]
    }

A badge that has already been issued to a recipient it can be revoked by posting a request to the api with some of the recipients details, if the recipient has been issued the badge previously it will now be revoked and removed from that recipients issued badges.

Arguments Information
recipient (string)
REQUIRED
Either the university email address or university card number of the user.

Returns

Returns a updated recipient

Collections

Collections are groups of badge around and area or activity. For example, the ‘Library’ or 'Trim Trail’.

Using the API, you can create, update and destroy collections.

The collection object

Example response

    {
        "id":"library",
        "name":"Library",
        "description":"Earn badges by using your Library",
        "total_points_available":"125",
        "badge_count":"4",
        "object":"collection",
        "created_at":"2015-03-25T13:28:44.144Z",
        "updated_at":"2015-03-25T13:28:44.144Z"
    }
Attributes Information
id
string
The unique id of the collection
name
string
Name of the collection must be unique
description
text
A description of how the badges relate to this collection
total_points_available
int
The total points available to be earned - the total of all live badges points in the collection.
badge_count
int
Number of live badges in the collection
object
string
What object the JSON represents.
created_at
datetime
The time and date of when a badge was first created
updated_at
datetime
The time and date of the last update to the badge

Create a collection

Definition

    POST https://badgeapi.lancaster.ac.uk/v1/collection
    collection = Badgeapi::Collection.create

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/collections
    -H "Authorization:  Token token=
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "collection" : {
            "name" : "New Collection",
            "description" : "This is a new collection"
        }}'
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    collection = Badgeapi::Collection.create(
        name: "New Collection",
        description: "This is a new collection"
    )

Example response

    {
        "id":"new-collection",
        "name":"New Collection",
        "description":"This is a new collection",
        "total_points_available":"0",
        "badge_count":"0",
        "object":"collection",
        "created_at":"2015-03-25T13:28:44.161Z",
        "updated_at":"2015-03-25T13:28:44.161Z"
    }

Collections can be created via the api by posting a JSON object of the required fields to the API.

Arguments Information
name (string)
REQUIRED
Name of the badge must be unique
description (text)
REQUIRED
A description of how the badges relate to this collection

Returns

Returns the created collection object if call succeeded. The returned object contains all the information about the collection.

Retrieve a collection

Definition

    GET https://badgeapi.lancaster.ac.uk/v1/collections/
    {COLLECTION_ID}
    collection = Badgeapi::Collection.find({COLLECTION_ID})

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/collections/library -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    collection = Badgeapi::Collection.find("library")

    collection.name #=> "Library"

Example response

    {
        "id":"library",
        "name":"Library",
        "description":"Earn badges by using your Library",
        "total_points_available":"125",
        "badge_count":"4",
        "object":"collection",
        "created_at":"2015-03-25T13:28:44.144Z",
        "updated_at":"2015-03-25T13:28:44.144Z"
    }

You can retrieve a single collections details by specifying the id of the collection you wish to retrieve

Arguments Information
id (string)
REQUIRED
The id of the collection to be retrieved.
expand (string)
OPTIONAL
Comma separated list to expand object. Valid values: badges

Returns

The collection object

Update a collection

Definition

    PATCH/PUT https://badgeapi.lancaster.ac.uk/v1/collections/{COLLECTION_ID}
    collection = Badgeapi::Collection.find({COLLECTION_ID})
    collection.name = {NEW_COLLECTION_NAME}
    ...
    collection.save

    # ALTERNATIVELY

    Badgeapi::Badge.Collection({BADGE_ID}, {PARAMETER}, {PARAMETER} ...)

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/collections/library -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -H "Content-Type: application/json"
    -d '{ "collection" : {
                "name" : "Library Updated"
    }}'
    --request PATCH
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    collection = Badgeapi::Collection.find("library")
    collection.name = "Library Updated"
    collection.save

    # ALTERNATIVELY

    Badgeapi::Collection.update("library",
        name: "Library Updated",
        description: "Updated Description"
    )

Example response

    {
        "id":"library",
        "name":"Library Updated",
        "description":"Updated Description",
        "total_points_available":"125",
        "badge_count":"4",
        "object":"collection",
        "created_at":"2015-03-25T13:28:44.144Z",
        "updated_at":"2015-03-30T13:00:44.144Z"
    }

Updates the specified collection by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments Information
name (string)
OPTIONAL
Name of the collection must be unique
description (text)
OPTIONAL
A description of how the badges relate to this collection

Returns

Returns the collection object if the update succeeded. Raises an error if update parameters are invalid.

Delete a collection

    DELETE https://badgeapi.lancaster.ac.uk/v1/collections/{COLLECTION_ID}
    collection = Badgeapi::Collection.destroy({COLLECTION_ID})

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/collections/library -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    -X DELETE
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

    collection = Badgeapi::Collection.destroy("library")

Example response

    {
        "id":"library",
        "name":"Library",
        "description":"Earn badges by using your Library",
        "total_points_available":"125",
        "badge_count":"4",
        "object":"collection",
        "created_at":"2015-03-25T13:28:44.144Z",
        "updated_at":"2015-03-25T13:28:44.144Z"
    }

Permanently deletes a collection. It cannot be undone. Also immediately destroys all badges in that collection. Use with caution!

Arguments Information
id (string)
REQUIRED
The id of the collection to be deleted.

Returns

Returns the deleted collection. If the badge does not exist returns an error.

List all collection

Definition

    GET https://badgeapi.lancaster.ac.uk/v1/collection
    collections = Badgeapi::Collection.all

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/badges -H
    "Authorization: Token
    token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

    collections = Badgeapi::Collection.all

    collections = Badgeapi::Collection.all expand: "badges"

Example response

    [
        {
            "id":"library",
            "name":"Library",
            "description":"Earn badges by using your Library",
            "total_points_available":"125",
            "badge_count":"4",
            "object":"collection",
            "created_at":"2015-03-25T13:28:44.144Z",
            "updated_at":"2015-03-25T13:28:44.144Z"
        },
        {"...":"..."},
        {"...":"..."},
        {"...":"..."}
    ]

You can retrieve a complete list of all available collections via the API

Arguments Information
limit (int)
OPTIONAL
Limit the number of collections retrieved.
expand (string)
OPTIONAL
Comma separated list to expand object. Valid values: badges

Returns

Returns a list of all available collections

Recipients

Recipients are the students and staff can earned and receive badges.

Using the API you can make a request for the recipient’s badges and stats using either their university card number or their university email.

The recipient object

Example response

    {
        "total_score":"75",
        "badges_total":"2",
        "bronze_count":"1",
        "silver_count":"1",
        "gold_count":"0",
        "platinum_count":"0",
        "object":"recipient",
        "badges": [
            {
                "id":"book-worm",
                "name":"Book Worm",
                "description":"Description?",
                "requirements":"Loan out 25 books",
                "hint":"You must like books...",
                "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                    book-worm/badge.png",
                "collection_id":"library",
                "level":"bronze",
                "points":"25",
                "auto_issue":"false",
                "object":"badge",
                "status":"live",
                "issued_at":"2015-07-16T09:21:22.849Z",
                "created_at":"2015-03-25T13:28:44.161Z",
                "updated_at":"2015-03-25T13:28:44.161Z"
            }
            {"...":"..."}
        ]
    }
Attributes Information
total_score
int
The total of points of the recipients earned badges
badges_total
int
The number of badges earned by the recipient
bronze_count
int
The number of earned bronze badges
silver_count
int
The number of earned silver badges
gold_count
int
The number of earned gold badges
platinum_count
int
The number of earned platinum badges
object
string
What object the JSON represents.
badges
Array
An array of the recipients badges with issued_at timestamp

Retrieve a recipient

Definition

    GET https://badgeapi.lancaster.ac.uk/v1/recipients?recipient={RECIPIENT}
    recipient = Badgeapi::Recipient.find(recipient: {RECIPIENT})

Example request

    curl https://badgeapi.lancaster.ac.uk/v1/recipient?recipient=t.skarbek-wazynski@lancaster.ac.uk
    -H "Authorization:Token token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    require "badgeapi"
    Badgeapi.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    Badgeapi.ssl_ca_cert = "/usr/lib/ssl/certs"

    recipient = Badgeapi::Recipient.find(
        recipient: "t.skarbek-wazynski@lancaster.ac.uk"
    )

    recipient.total_score #=> 75

Example response

    {
        "total_score":"75",
        "badges_total":"2",
        "bronze_count":"1",
        "silver_count":"1",
        "gold_count":"0",
        "platinum_count":"0",
        "object":"recipient",
        "badges": [
            {
                "id":"book-worm",
                "name":"Book Worm",
                "description":"Description?",
                "requirements":"Loan out 25 books",
                "hint":"You must like books...",
                "image":"https://badgeapi.lancaster.ac.uk/badge_images/
                    book-worm/badge.png",
                "collection_id":"library",
                "level":"bronze",
                "points":"25",
                "auto_issue":"false",
                "object":"badge",
                "status":"live",
                "issued_at":"2015-07-16T09:21:22.849Z",
                "created_at":"2015-03-25T13:28:44.161Z",
                "updated_at":"2015-03-25T13:28:44.161Z"
            }
            {"...":"..."}
        ]
    }

You can retrieve a single recipient details by specifying either the university email or university card number of the recipient you wish to retrieve.

Arguments Information
recipient (string)
REQUIRED
Either the university email address or university card number of the user.

Returns

The recipient object