REST API for Badges

Base URL for all REST calls is /api/badges

Get list of badges

GET /api/badges/badges

Optional CGI-style parameters:

• assigned_to=:user_id - Filter badges by assigned user
• not_assigned_to=:user_id - Filter badges not assigned to a user
• status=:status - Filter badges by status, defaults to "live"
• search=:search - Filter badges by the badge title or description
• include_assignees=true - Include an array of user_ID/name pairs who have each badge

Only one of assigned_to and not_assigned_to can be used at a time. If both are supplied not_assigned_to will be ignored.

:status can have one of these values:

• live
• archived
• all

Returns JSON-formatted array of badges. Each badge has the following format:

{
    "id": 5,
    "title": "Creative Thinker",
    "description": "Thinks outside the box, solves problems in a creative way ",
    "image_id": 256,
    "image": "<domain>/appdata/badges/256.jpg?1563285324",
    "background_colour": "689F38",
    "status": "live",
    "created_by": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "created_date": {
        "date_str" : "2011-04-08 18:13:00",
        "timezone" : "Asia/Novosibirsk",
        "date" : "20110513111311"
    },
    "modified_by": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "modified_date": {
        "date_str" : "2011-05-13 18:13:00",
        "timezone" : "Asia/Novosibirsk",
        "date" : "20110513111311"
    },
    "assignees": [
        {
            "id": 1,
            "name":  "Claromentis administrator",
            "profileUrl": "<domain>/people/user/73935872",
            "imageUrl": "<domain>/appdata/people/1.jpg?1558630388"
        },
        {
            "id": 2,
            "name":  "Bobby Tables",
            "profileUrl": "<domain>/people/user/73935873",
            "imageUrl": "<domain>/appdata/people/2.jpg?1558630388"
        }
    ],
    "assigned": {
        "assigned_by": {
            "id": 1234,
            "name": "Michael Christian"
        },
        "assigned_to": {
          "id": 1,
          "name": "Claromentis Administrator",
          "image_url": "<domain>/appdata/people/1.jpg?1558630388",
          "profile_url": "<domain>/people/user/73935872"
        },
        "assigned_date": {
            "date_str" : "2011-05-13 18:13:00",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "message": "Congratulations"
    }
}

Get a badge

GET /api/badges/badge/:id

Gets a single badge by ID

Optional CGI-style parameters:

• include_assignees=true - Include an array of user_ID/name pairs who have each badge

Returns JSON-formatted badge in the following format :

{
    "id": 1,
    "title": "Badge name",
    "description": "A badge",
    "image_id": 25,
    "image": "<domain>/intranet/badges/images/024-thinking.svg",
    "background_colour": "B71C1C",
    "status": "live",
    "created_by": {
        "id": 1,
        "name": "Claromentis Administrator"
    },
    "created_date": {
        "date_str": "15-10-2019 11:28",
        "timezone": "Europe/London",
        "date": "20191015102837"
    },
    "modified_by": [],
    "modified_date": {
        "date_str": "15-10-2019 11:28",
        "timezone": "Europe/London",
        "date": "20191015102837"
    },
    "archived_by": [],
    "archived_date": [],
    "assigned": [
        {
            "assigned_by": {
                "id": 1,
                "name": "Claromentis Administrator"
            },
            "assigned_to": {
                "id": 1,
                "name": "Claromentis Administrator",
                "image_url": "<domain>/intranet/people/images/no_photo.jpg",
                "profile_url": "<domain>/people/user/73935872"
            },
            "assigned_date": {
                "date": {
                    "date_str": "15-10-2019 11:29",
                    "timezone": "Europe/London",
                    "date": "20191015102952"
                }
            },
            "message": "Congratulations on being awarded this badge"
        }
    ]
}

Add a badge

POST /api/badges/badges

Create a new badge

The request body should contain JSON-formatted data with information about new badge:

{
    "title": "Creative Thinker",
    "description": "Thinks outside the box, solves problems in a creative way ",
    "image_id": 256,
    "status": "live",
    "background_colour": "2196f3"
}

Returns JSON containing the new badge data if successful

{
    "message": "Badge created",
    "badge": {...}
}

Edit a badge

PUT /api/badges/badges/:id

Edit an existing badge

The request body should contain JSON-formatted data with changed information about new badge.

Optionally any of these fields can be left out so that only actual changes are transmitted. Fields not mentioned will not be modified:

{
    "title": "Creative Thinker",
    "description": "Thinks outside the box, solves problems in a creative way ",
    "image_id": 256,
    "status": "live",
    "background_colour": "2196f3"
}

Returns JSON containing the new badge data if successful

{
    "message": "Badge updated",
    "badge": {...}
}

Delete a badge

DELETE /api/badges/badges/:id

Returns JSON containing a message

{
    "message": "Badge deleted"
}

Assign a badge

POST /api/badges/badges/assign

Assign multiple badges to multiple users

The request body should contain JSON-formatted data with information about assignments:

{
    "badge_ids":  [1, 2, 3],
    "user_ids": [123, 234, 345],
    "message": "Have some badges"
}

Returns JSON containing a status message

{
    "message": "Badge successfully assigned"
}

Unassign a badge

POST /api/badges/badges/unassign/:badge_id

Unassign a badge from multiple users

The request body should contain JSON-formatted data with information which users to remove from each badge:

{
    "user_ids": [123, 234, 345]
}

Returns JSON containing a status message

{
    "message": "Badge successfully unassigned"
}

Get image sets

GET /api/badges/image-sets

Returns JSON-formatted array of image sets. Each set has the following format:

{
    "id": 1,
    "title": "Claromentis default set"
}

note in the initial version of Badges the image sets are fixed as 0 = custom images, 1 = pre-defined icons. This may or not change in later versions.

Get images in all sets

GET /api/badges/image-sets/images

Returns JSON-formatted array of image data. Each image has the following format:

{
    "id": 1,
    "image_url": "<domain>/badges/images/1",
    "set_id": 1
}

Get images in set

GET /api/badges/image-sets/:id/images

Returns JSON-formatted array of image data. Each image has the following format:

{
    "id": 1,
    "image_url": "<domain>/badges/images/1",
    "set_id": 1
}

Add images to custom set

POST /api/badges/image-sets/:id/images

The request body should contain either an image and the original filename as the payload, or a JSON-formatted body for uploads via the croptool. This JSON will be an array to allow multiple uploads with the same request:

[
    {
        "hash": "img_jCjTcs"
    },
    {
        "hash": "img_aBcdEf"
    }
]

Returns JSON containing a status message and image IDs

{
    "message": "Image successfully added",
    "ids": [1, 2]
}

Delete custom image

DELETE /api/badges/images/:id

:id must be that of an image in the custom image set

Returns JSON containing a status message

{
    "message": "Image deleted"
}

Bad request

Currently this is the only defined error that should be returned by Badges itself from any of the described REST endpoints. It will be an HTTP 400 code with the following fields.

{
    "status": 400,
    "type": "https://developer.claromentis.com/v8.8/api/badges.html#bad_request",
    "title": "Bad request",
    "detail": "No image file uploaded",
    "instance": "/api/badges/images-sets/1/images"
}