diff --git a/README.md b/README.md index 3c2b746..a7f111f 100644 --- a/README.md +++ b/README.md @@ -10,19 +10,21 @@ __The BadgeKit Web app links to the API to create an admin user interface for cr The BadgeKit API provides a series of endpoints through which your sites can interact with data for badges, earner applications and issuer organization admin. Below are some examples of calls you can make to the API. -Retrieve/ Update/ Add new: -* badges -* earner applications for badges -* application reviews -* _issuers within a system_ -* _programs within an issuer_ -* _badge/ application data for a particular issuers/ programs_. +* Retrieve badges +* Submit earner applications for badges +* Submit application reviews +* Issue badges +* Generate claim codes for a badge +* Update badge data +* Manage badges within system, issuer and program admin levels __Using issuer and program admin levels is entirely optional - you can simply configure BadgeKit to group all of your badge and application data within a single system.__ +The repo [docs](docs) list all of the available endpoints provided by the API, together with examples of request and response data. + When you make a request, the API returns JSON data. You can then present the returned data within your own site interface. -In addition to the series of calls you can make to interact with data, the API also provides webhooks for badging events (such as a badge being issued or an earner application being reviewed). By configuring a URL to receive notification of these events, you can build your own custom responses, for example informing an earner that their badge application was successful. +In addition to the series of calls you can make to interact with data, the API also provides [webhooks](docs/webhooks.md) for badging events (such as a badge being issued or an earner application being reviewed). By configuring a URL to receive notification of these events, you can build your own custom responses, for example informing an earner that their badge application was successful. To get started accessing the API in your own sites, see [Using BadgeKit API](https://github.com/mozilla/badgekit-api/wiki/Using-BadgeKit-API). @@ -34,16 +36,16 @@ API calls should be signed with a JWT token generated using the secret for your To install the BadgeKit API: * clone the repo -* set up a database -* set your environment configs. +* set your environment configs +* set up your database -You can use the `schema.sql` file in the root directory to create your database. You also need to add an entry in the `system` table, providing an initial slug and system name for a badge issuing system. See the [wiki](https://github.com/mozilla/badgekit-api/wiki) for more details and the [Self-Hosting guide](https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-Self-Hosting-Guide) if you plan on building your own instance of the BadgeKit Web app as well as the API. +You can use `bin/db-migrate up` from the root directory to create (or migrate) your database. You also need to add an entry in the `systems` table, providing an initial slug, system name and URL (optionally also description, email and image) for a badge issuing system. See the [wiki](https://github.com/mozilla/badgekit-api/wiki) for more details and the [Self-Hosting guide](https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-Self-Hosting-Guide), particularly if you plan on building your own instance of the BadgeKit Web app as well as the API. ## Environment Configuration -The BadgeKit API currently uses the following configuration details: +BadgeKit API currently uses the following configuration details: -* `NODE_ENV`: Set to `production` for production environments. If you want to run the test suite, set this to `test`. **DO NOT SET THIS TO `test` ON PRODUCTION MACHINES, BAD THINGS WILL HAPPEN** - mainly authentication will be inactive and you run the risk of accidentally dropping your database. +* `NODE_ENV`: Set to `production` for production environments. If you want to run the test suite or to try out the API endpoints without JWT authorization, set this to `test`. **DO NOT SET THIS TO `test` ON PRODUCTION MACHINES, BAD THINGS WILL HAPPEN** - _authentication will be inactive and you run the risk of accidentally dropping your database_. * `DB_HOST`: Defaults to `localhost`. * `DB_NAME`: Name of the database to store BadgeKit data. * `DB_USER`: User who has full access to the `DB_NAME` table. diff --git a/docs/README.md b/docs/README.md index fc5bc35..411d858 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ The BadgeKit API docs include the information you need to get started using the * [Webhooks](webhooks.md) * [Authorization](authorization.md) -You can interact with badge and application data managed by the API using the endpoints. The data you send to the API endpoints needs to be signed for authentication, and the data you receive from the API (in responses and webhook messages) is signed before it is sent. To detect badging events carried out through the API, such as badges being issued and badge applications being reviewed, you can configure a webhook URL to which BadgeKit API will send data. +You can interact with badge and application data managed by the API using the endpoints. The data you send to the API endpoints needs to be signed for authentication, and the data you receive from the API (in responses and webhook messages) is signed before it is sent. To detect badging events carried out through the API, such as badges being issued/ revoked and badge applications being reviewed, you can configure a webhook URL to which BadgeKit API will send data. The API docs provide a reference for the endpoints and webhooks. You will also find detailed guides to carrying out common processes, including the assessment flow, together with sample code excerpts, in the [BadgeKit API wiki](https://github.com/mozilla/badgekit-api/wiki): diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index 4c19411..da63a74 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -38,6 +38,7 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **DELETE** /systems/:slug/badges/:slug * **DELETE** /systems/:slug/issuers/:slug/badges/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug + * **GET** /public/badges * [Claim Codes](claim-codes.md) * **GET** /systems/:slug/codes/:code * **GET** /systems/:slug/issuers/:slug/codes/:code @@ -118,11 +119,3 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **DELETE** /systems/:slug/milestones/:milestoneId See also [authorization](authorization.md) and [webhooks](webhooks.md). - - diff --git a/docs/assessment.md b/docs/assessment.md index 6579787..b727ce7 100644 --- a/docs/assessment.md +++ b/docs/assessment.md @@ -12,8 +12,8 @@ Assessment therefore involves two objects in BadgeKit API: applications and revi | `slug` | __string__ | | `learner` | __email address__ - _earner email_ | | `created` | __timestamp__ | -| `assignedTo` | __string__ - _email login for assigned reviewer_ | -| `assignedExpiration` | __timestamp__ | +| `assignedTo` | __string__ - _email address for assigned reviewer_ | +| `assignedExpiration` | __timestamp__ - _expiry date for assigned reviewer to complete review, after which another reviewer can be assigned_ | | `badge` | [badge](badges.md) - _badge applied for_ | | `processed` | __timestamp__ - _e.g. set when review is submitted or when badge instance is created_ | | `evidence` | __array__ - _each evidence item can include: `url`, `mediaType` (which can be `image` or `link`) and `reflection` (which is a string)_ | @@ -27,7 +27,6 @@ Assessment therefore involves two objects in BadgeKit API: applications and revi | `author` | __email address__ - _reviewer email_ | | `comment` | __string__ - _applicant feedback_ | | `reviewItems` | __array__ - _one for each criteria item in the badge; each reviewItem can include: `criterionId`, `satisfied` status and `comment`_ | -| `approved` | __boolean__ - _indicates success of application_ | ## Endpoints @@ -90,6 +89,13 @@ GET /systems/:slug/issuers/:slug/badges/:slug/applications GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//applications?count=2&page=1` + ### Expected response ``` @@ -130,10 +136,19 @@ Content-Type: application/json ] }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +Applications are returned in order sorted by created date. + +__`pageData` is returned when pagination parameters are used.__ + #### Response structure * applications `[ ]` @@ -261,7 +276,7 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` | **learner** | required | The email address for the earner applying. | | **evidence** | optional | Array including evidence items - each item can include `reflection`, `mediaType` and `url`. | | **assignedTo** | optional | Email of reviewer application is assigned to. | -| **assignedExpiration** | optional | Expiry date. | +| **assignedExpiration** | optional | Expiry date for assigned reviewer to complete review. | ### Expected response @@ -359,7 +374,7 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` | **learner** | The email address for the earner applying. | | **evidence** | Array including evidence items - each item can include `reflection`, `mediaType` and `url`. | | **assignedTo** | Email of reviewer application is assigned to. | -| **assignedExpiration** | Expiry date. | +| **assignedExpiration** | Expiry date for assigned reviewer to complete review. | | **processed** | Timestamp indicating application has been processed. | You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. @@ -507,6 +522,13 @@ GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//badges//applications//reviews?count=2&page=1` + ### Expected response ``` @@ -532,10 +554,17 @@ Content-Type: application/json ] }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * reviews `[ ]` diff --git a/docs/badges.md b/docs/badges.md index 225ca7a..ea34dcb 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -5,7 +5,7 @@ A badge represents the generic data for an earnable badge (not an awarded badge, | NAME | VALUE | |:---|:---| | `id` | __integer__ - _ID from database entry._ | -| `slug` | __string__ - _Used to identify badge in API endpoints._ | +| `slug` | __string__ - _Used to identify badge in API endpoints (auto-generated)._ | | `name` | __string__ - _Display name._ | | `strapline` | __string__ - _Short tagline description._ | | `earnerDescription` | __string__ - _Description for potential earners._ | @@ -22,6 +22,8 @@ A badge represents the generic data for an earnable badge (not an awarded badge, | `type` | __string__ - _Badges can be organized by type and category._ | | `archived` | __boolean__ - _Archived badges can no longer be earned._ | | `system` | __integer__ - _System is represented by ID in database - system details are returned from API endpoints as nested JSON._ | +| `issuer` | __integer__ - _Isuser is represented by ID in database - issuer details are returned from API endpoints as nested JSON._ | +| `program` | __integer__ - _Program is represented by ID in database - program details are returned from API endpoints as nested JSON._ | | `criteriaUrl` | __string__ - _Link to criteria material._ | | `criteria` | __array__ - _Each item includes `id`, `description`, `required` status and `note`._ | | `categories` | __array__ - _See above for related type field._ | @@ -50,6 +52,8 @@ A badge represents the generic data for an earnable badge (not an awarded badge, * `DELETE /systems//badges/` * `DELETE /systems//issuers//badges/` * `DELETE /systems//issuers//programs//badges/` +* [Retrieve Public Badge Class List](#retrieve-public-badge-class-list) + * `GET /public/badges` ## Retrieve Badge List @@ -69,6 +73,10 @@ GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges * `true` will return only archived badges * `false` (default) will return only unarchived badges * `any` will return badges regardless of archived status +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//badges?archived=false&count=2&page=1` ### Expected response @@ -106,7 +114,26 @@ Content-Type: application/json "email": "admin@systemsite.com", "imageUrl": "http://systemsite.com/image.jpg", "issuers": [ ] - } + }, + "issuer": { + "id": 1, + "slug": "issuer-slug", + "url": "http://issuersite.com", + "name": "Issuer Name", + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ ] + }, + "program": { + "id": 1, + "slug": "program-slug", + "url": "http://programsite.com", + "name": "Program Name", + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" + }, "criteriaUrl": "http://issuersite.com/criteria", "criteria": [ { @@ -122,10 +149,17 @@ Content-Type: application/json "milestones": [ ] }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * badges `[ ]` @@ -146,14 +180,31 @@ Content-Type: application/json * imageUrl * type * archived - * [system](systems.md) `[ ]` + * [system](systems.md) + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * [issuer](issuers.md) + * id + * slug + * url + * name + * description + * email + * imageUrl + * programs `[ ]` + * [program](programs.md) * id * slug * url * name + * description * email * imageUrl - * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -217,6 +268,25 @@ Content-Type: application/json "imageUrl": "http://systemsite.com/image.jpg", "issuers": [ ] }, + "issuer": { + "id": 1, + "slug": "issuer-slug", + "url": "http://issuersite.com", + "name": "Issuer Name", + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ ] + }, + "program": { + "id": 1, + "slug": "program-slug", + "url": "http://programsite.com", + "name": "Program Name", + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" + }, "criteriaUrl": "http://issuersite.com/criteria", "criteria": [ { @@ -254,14 +324,31 @@ Content-Type: application/json * imageUrl * type * archived - * [system](systems.md) `[ ]` + * [system](systems.md) + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * [issuer](issuers.md) * id * slug * url * name + * description + * email + * imageUrl + * programs `[ ]` + * [program](programs.md) + * id + * slug + * url + * name + * description * email * imageUrl - * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -304,7 +391,6 @@ POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges | Parameters | Required | Description | |:-----------------------|-----------------|--------------------------| -| **slug** | _required_ | Short, computer-friendly name for the badge. Good slugs are lowercase and use dashes instead of spaces, e.g. `reading-badge`. Maximum of 50 characters and each badge must have a unique slug. | **name** | _required_ | Name of the badge. Maximum 255 characters. | **image** OR **imageUrl** | _required_ | Image for the program. Should be either multipart data or a URL. | **unique** | _required_ | Boolean indicator of whether an earner can earn the badge only once. @@ -362,6 +448,25 @@ Content-Type: application/json "imageUrl": "http://systemsite.com/image.jpg", "issuers": [ ] }, + "issuer": { + "id": 1, + "slug": "issuer-slug", + "url": "http://issuersite.com", + "name": "Issuer Name", + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ ] + }, + "program": { + "id": 1, + "slug": "program-slug", + "url": "http://programsite.com", + "name": "Program Name", + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" + }, "criteriaUrl": "http://issuersite.com/criteria", "criteria": [ { @@ -400,14 +505,31 @@ Content-Type: application/json * imageUrl * type * archived - * [system](systems.md) `[ ]` + * [system](systems.md) + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * [issuer](issuers.md) * id * slug * url * name + * description + * email + * imageUrl + * programs `[ ]` + * [program](programs.md) + * id + * slug + * url + * name + * description * email * imageUrl - * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -442,37 +564,6 @@ Content-Type: application/json } ``` -* **Duplicate entry** - -``` - HTTP/1.1 409 Conflict - Content-Type: application/json -``` - -```json - { - "code": "ResourceConflict", - "error": "badge with that `slug` already exists", - "details": { - "name": "Badge Name", - "slug": "badge-slug", - "strapline": "Badge strapline.", - "earnerDescription": "Badge description for earners.", - "consumerDescription": "Badge description for consumers.", - "issuerUrl": "http://issuersite.com", - "rubricUrl": "http://issuersite.com/rubric", - "criteriaUrl": "http://issuersite.com/criteria", - "timeValue": 10, - "timeUnits": "minutes", - "evidenceType": "URL", - "limit": 5, - "unique": false, - "imageUrl": "http://issuersite.com/badge.png", - "archived": false - } - } -``` - ## Update a Badge Updates an existing badge. @@ -489,7 +580,6 @@ PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badge | Parameters | Description | |:-----------------------|--------------------------| -| **slug** | Short, computer-friendly name for the badge. Good slugs are lowercase and use dashes instead of spaces, e.g. `reading-badge`. Maximum of 50 characters and each badge must have a unique slug. | **name** | Name of the badge. Maximum 255 characters. | **image** OR **imageUrl** | Image for the program. Should be either multipart data or a URL. | **unique** | Boolean indicator of whether an earner can earn the badge only once. @@ -549,6 +639,25 @@ Content-Type: application/json "imageUrl": "http://systemsite.com/image.jpg", "issuers": [ ] }, + "issuer": { + "id": 1, + "slug": "issuer-slug", + "url": "http://issuersite.com", + "name": "Issuer Name", + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ ] + }, + "program": { + "id": 1, + "slug": "program-slug", + "url": "http://programsite.com", + "name": "Program Name", + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" + }, "criteriaUrl": "http://issuersite.com/criteria", "criteria": [ { @@ -580,21 +689,38 @@ Content-Type: application/json * rubricUrl * timeValue * timeUnits - * evidenceType + * evidenceType * limit * unique * created * imageUrl * type * archived - * [system](systems.md) `[ ]` + * [system](systems.md) * id * slug * url * name * email * imageUrl - * [issuers](issuers.md) `[ ]` + * issuers `[ ]` + * [issuer](issuers.md) + * id + * slug + * url + * name + * description + * email + * imageUrl + * programs `[ ]` + * [program](programs.md) + * id + * slug + * url + * name + * description + * email + * imageUrl * criteriaUrl * criteria `[ ]` * id @@ -629,37 +755,6 @@ Content-Type: application/json } ``` -* **Duplicate entry** - -``` - HTTP/1.1 409 Conflict - Content-Type: application/json -``` - -```json - { - "code": "ResourceConflict", - "error": "badge with that `slug` already exists", - "details": { - "name": "Badge Name", - "slug": "badge-slug", - "strapline": "Badge Strapline", - "earnerDescription": "Badge Description", - "consumerDescription": "Badge Description for Consumers", - "issuerUrl": "http://example.org/issuer", - "rubricUrl": "http://example.org/rubric", - "criteriaUrl": "http://example.org/criteria", - "timeValue": 10, - "timeUnits": "minutes", - "evidenceType": "URL", - "limit": 5, - "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false - } - } -``` - * **Badge not found** ``` @@ -738,3 +833,45 @@ Content-Type: application/json "message": "Could not find badge field: `slug`, value: " } ``` + +## Retrieve Public Badge Class List + +Retrieves list of public badge classes - API returns URL for each badge class. + +__The authorization header is not required for this endpoint.__ + +### Expected request + +``` +GET /public/badges +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "badgelist": [ + { + "location": "http://issuersite.com/public/systems/system-slug/badges/badge-slug" + }, + { + "location": "http://issuersite.com/public/systems/system-slug/issuers/issuer-slug/programs/program-slug/badges/badge-slug" + }, + ... + ] +} +``` + +#### Response structure + +* badgelist `[ ]` + * location + +### Potential errors + +*None* diff --git a/docs/claim-codes.md b/docs/claim-codes.md index 4cc2806..a74bc30 100644 --- a/docs/claim-codes.md +++ b/docs/claim-codes.md @@ -54,6 +54,13 @@ GET /systems/:slug/issuers/:slug/badges/:slug/codes GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//badges//codes?count=2&page=1` + ### Expected response ``` @@ -75,10 +82,17 @@ Content-Type: application/json ], "badge": { ... + }, + "pageData": { + "page": 1, + "count": 2, + "total": 4 } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * claimCodes `[ ]` @@ -195,6 +209,12 @@ Content-Type: application/json "system": { ... }, + "issuer": { + ... + }, + "program": { + ... + }, "criteriaUrl": "http://issuersite.com/criteria", "criteria": [ ], "categories": [ ], diff --git a/docs/issuers.md b/docs/issuers.md index 36dfd01..53cfe04 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -31,6 +31,13 @@ Retrieves all available issuers in the specified system. GET /systems/:systemSlug/issuers ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//issuers?count=2&page=1` + ### Expected response ``` @@ -63,10 +70,17 @@ Content-Type: application/json ] }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * issuers `[ ]` diff --git a/docs/issuing.md b/docs/issuing.md index 223332b..9b229b0 100644 --- a/docs/issuing.md +++ b/docs/issuing.md @@ -48,6 +48,13 @@ GET /systems/:slug/issuers/:slug/badges/:slug/instances GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//badges//instances?count=2&page=1` + ### Expected response ``` @@ -64,7 +71,7 @@ Content-Type: application/json "expires": "2014-10-29T10:16:01.000Z", "issuedOn": "2014-05-29T10:16:01.000Z", "claimCode": "claim-code", - "assertionURl": "http://issuersite.com/public/assertions/instance-slug", + "assertionUrl": "http://issuersite.com/public/assertions/instance-slug", "badge": { "id": 1, "slug": "badge-slug", @@ -72,10 +79,17 @@ Content-Type: application/json } }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * instances `[ ]` @@ -117,28 +131,26 @@ Content-Type: application/json ```json { - "instances": [ + "instance": { "slug": "instance-slug", "email": "earneremail@adomain.com", "expires": "2014-10-29T10:16:01.000Z", "issuedOn": "2014-05-29T10:16:01.000Z", "claimCode": "claim-code", - "assertionURl": "http://issuersite.com/public/assertions/instance-slug", + "assertionUrl": "http://issuersite.com/public/assertions/instance-slug", "badge": { "id": 1, "slug": "badge-slug", ... } - }, - ... - ] + } } ``` #### Response structure -* instances `[ ]` +* instance * slug * email * expires diff --git a/docs/milestones.md b/docs/milestones.md index 87d20fa..9fa5641 100644 --- a/docs/milestones.md +++ b/docs/milestones.md @@ -2,6 +2,8 @@ Milestones give issuers the ability to award badges in recognition that the earner has earned a set of other badges. A milestone badge therefore represents a higher-level achievement, with the contributing badges representing more granular badges, culminating in the milestone. A milestone badge can be defined as available to earners of a specific set of other badges. +__When an earner is awarded a set of badges that makes them eligible to earn a milestone badge, the API will automatically issue the milestone badge to the earner by creating a new badge instance. The `award` webhook fires for a milestone badge as it does for other badges.__ + | NAME | VALUE | |:---|:---| | `id` | __integer__ - _id from database_ | @@ -16,6 +18,8 @@ Milestones give issuers the ability to award badges in recognition that the earn * [`POST /systems/:slug/milestones`](#post-systemsslugmilestones) * [`PUT /systems/:slug/milestones/:milestoneId`](#put-systemsslugmilestonesmilestoneid) * [`DELETE /systems/:slug/milestones/:milestoneId`](#delete-systemsslugmilestonesmilestoneid) +* [`POST /systems/:slug/milestones/:milestoneId/add-badge`](#post-systemsslugmilestonesmilestoneidadd-badge) +* [`POST /systems/:slug/milestones/:milestoneId/remove-badge`](#post-systemsslugmilestonesmilestoneidremove-badge) ## `GET /systems/:slug/milestones` @@ -27,6 +31,13 @@ Retrieve milestones within a system. GET /systems//milestones ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//milestones?count=2&page=1` + ### Expected response ``` @@ -73,10 +84,17 @@ Content-Type: application/json ... ] } - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * milestones `[ ]` @@ -483,3 +501,281 @@ Content-Type: application/json "message": "Could not find milestone with `id` " } ``` + +## `POST /systems/:slug/milestones/:milestoneId/add-badge` + +Add a badge to a milestone. + +### Expected request + +``` +POST /systems//milestones//add-badge +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Description | +|:-----------------------|--------------------------| +| **badgeId** | ID of badge being added to the milestone | + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "updated", + "milestone": { + "id": 1, + "action": "issue", + "numberRequired": 3, + "primaryBadge": { + "id": 4, + "slug": "milestone-slug", + "name": "Big Milestone Badge", + "strapline": "Recognises milestone stuff.", + "earnerDescription": "You achieved a milestone.", + "consumerDescription": "Earner achieved a milestone.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-06-13T18:49:33.000Z", + "type": "", + "archived": false, + "criteriaUrl": "http://issuersite.com/badge/big-milestone-badge/criteria", + "criteria": [ ], + "alignments": [ ], + "evidenceType": null, + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + "supportBadges": [ + { + "id": 1, + "slug": "badge-slug", + "name": "New Badge", + "strapline": "This badge shows excellence.", + "earnerDescription": "You are excellent if you earn this badge.", + "consumerDescription": "Earners of this badge are excellent.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-06-11T15:36:49.000Z", + "type": "", + "archived": false, + "criteriaUrl": "http://issuersite.com/badge/new-badge/criteria", + "criteria": [ ], + "alignments": [ ], + "evidenceType": null, + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + ... + + ] + } +} +``` + +#### Response structure + +* status +* milestone + * id + * action + * numberRequired + * primaryBadge ([badge](badges.md)) + * id + * slug + * ... + * supportBadges `[ ]` + * id + * slug + * ... + +#### Potential Errors + +* **Invalid data** + +``` + HTTP/1.1 400 Bad Request + Content-Type: application/json +``` + +```json + { + "code": "ValidationError", + "message": "Could not validate required fields", + "details": [ + { + "field": "id", + "value": "..." + }, + ... + ] + } +``` + +* **Milestone not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "NotFoundError", + "message": "Could not find milestone with `id` " +} +``` + +## `POST /systems/:slug/milestones/:milestoneId/remove-badge` + +Remove a badge from a milestone. + +### Expected request + +``` +POST /systems//milestones//remove-badge +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Description | +|:-----------------------|--------------------------| +| **badgeId** | ID of badge being removed from the milestone | + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "updated", + "milestone": { + "id": 1, + "action": "issue", + "numberRequired": 3, + "primaryBadge": { + "id": 4, + "slug": "milestone-slug", + "name": "Big Milestone Badge", + "strapline": "Recognises milestone stuff.", + "earnerDescription": "You achieved a milestone.", + "consumerDescription": "Earner achieved a milestone.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-06-13T18:49:33.000Z", + "type": "", + "archived": false, + "criteriaUrl": "http://issuersite.com/badge/big-milestone-badge/criteria", + "criteria": [ ], + "alignments": [ ], + "evidenceType": null, + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + "supportBadges": [ + { + "id": 1, + "slug": "badge-slug", + "name": "New Badge", + "strapline": "This badge shows excellence.", + "earnerDescription": "You are excellent if you earn this badge.", + "consumerDescription": "Earners of this badge are excellent.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-06-11T15:36:49.000Z", + "type": "", + "archived": false, + "criteriaUrl": "http://issuersite.com/badge/new-badge/criteria", + "criteria": [ ], + "alignments": [ ], + "evidenceType": null, + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + ... + + ] + } +} +``` + +#### Response structure + +* status +* milestone + * id + * action + * numberRequired + * primaryBadge ([badge](badges.md)) + * id + * slug + * ... + * supportBadges `[ ]` + * id + * slug + * ... + +#### Potential Errors + +* **Invalid data** + +``` + HTTP/1.1 400 Bad Request + Content-Type: application/json +``` + +```json + { + "code": "ValidationError", + "message": "Could not validate required fields", + "details": [ + { + "field": "id", + "value": "..." + }, + ... + ] + } +``` + +* **Milestone not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "NotFoundError", + "message": "Could not find milestone with `id` " +} +``` diff --git a/docs/programs.md b/docs/programs.md index 242fe29..daca045 100644 --- a/docs/programs.md +++ b/docs/programs.md @@ -30,6 +30,13 @@ Retrieves all available programs in the specified system and issuer. GET /systems/:systemSlug/issuers/:issuerSlug/programs ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems//issuers//programs?count=2&page=1` + ### Expected response ``` @@ -50,9 +57,17 @@ Content-Type: application/json "imageUrl": "http://programsite.com/image.jpg" }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` + +_`pageData` is returned when pagination parameters are used._ + #### Response structure * programs `[ ]` diff --git a/docs/systems.md b/docs/systems.md index 8b2e890..5265ede 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -31,6 +31,13 @@ Retrieves all available systems in the BadgeKit API instance. GET /systems ``` +#### Available request parameters + +* **`page`:** - page of results to return +* **`count`:** - count of results to return per page + +e.g. `/systems?count=2&page=1` + ### Expected response ``` @@ -75,10 +82,17 @@ Content-Type: application/json ] }, ... - ] + ], + "pageData": { + "page": 1, + "count": 2, + "total": 4 + } } ``` +_`pageData` is returned when pagination parameters are used._ + #### Response structure * systems `[ ]` diff --git a/docs/webhooks.md b/docs/webhooks.md index c765a6c..eecf0c3 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -8,7 +8,7 @@ BadgeKit will send data to your webhook URL when these events occur: * [An application review is submitted](#new-application-review-submitted) * [A badge is awarded/issued (a badge instance is created)](#new-badge-instance-created) -* [A badge is revoked (a badge instance is deleted)](#new-badge-instance-deleted) +* [A badge is revoked (a badge instance is deleted)](#badge-instance-deleted) ## Authentication