📙 Knowledge Base Tip: Review the Badge API Specifications article before utilizing HelioCampus Badge API Endpoints.
Create or Update a Badge
POST: /badges?institutionCode=<institution code>
PUT: /badges/{badgeId}
Request Body:
-
All fields are required.
-
The “image” field should be in base64 encoded format.
-
The "code" field must be unique among badges.
-
The “owner” field assigns the owning Institution/College/Department/Administrative Unit/Administrative Division. If “owner” is left blank, ‘Institution’ will be automatically entered as the badge owner.
Images should conform to the following specifications:
-
PNG or SVG file type [5]
-
Images should be square (equal width and height) [5]
-
Image file size should not exceed 256k [6]
-
Image dimensions should be no smaller than 90 x 90 pixels [5] [6]
-
Recommended image size varies by badging platform. For PNG files, most recommend an image size of 400 x 400 – 600 x 600 pixels.
If successful, it returns the JSON resource with its URL in the Location header and the same response as the GET request in the body. If the badge has existing assertions when PUT request was sent, it returns 403 Forbidden as an endpoint response and doesn't allow badge update.
The following are style considerations when designing badges.
-
The badge image, together with the badge name, are typically the first thing badge consumers will see, and together the name and image should be capable of providing a sense of what the badge is about.
-
The badge image may contain issuer branding. However, because badges can be displayed at sizes as small as 90 x 90 pixels, take care that branding remains legible/visually appealing.
-
Badges may be displayed at different sizes. Preview the image at around 90x90 device pixels to ensure that elements are clear. This is around the smallest size that applications commonly embed badge images on the web [5].
-
Badges are portable and may be displayed in a variety of digital contexts and against different background colors [5].
Read a Badge
GET: /badges/<Badge Id>
If successful, it returns the JSON resource request in the body.
Response Body:
📔 Additional Resources