From 811182957ea02c9d4476311108e6d4426cd20b5d Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 21 May 2014 18:12:46 +0100 Subject: [PATCH 01/61] Initial pass through endpoints. --- docs/api-endpoints.md | 69 ++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 33 deletions(-) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index aa80bc2..29932e4 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -5,18 +5,21 @@ * **GET** /systems/:slug * **PUT** /systems/:slug * **DELETE** /systems/:slug + * **GET** /public/systems/:slug * Issuers * **GET** /systems/:slug/issuers * **POST** /systems/:slug/issuers * **GET** /systems/:slug/issuers/:slug * **PUT** /systems/:slug/issuers/:slug * **DELETE** /systems/:slug/issuers/:slug + * **GET** /public/systems/:slug/issuers/:slug * Programs * **GET** /systems/:slug/issuers/:slug/programs * **POST** /systems/:slug/issuers/:slug/programs * **GET** /systems/:slug/issuers/:slug/programs/:slug * **PUT** /systems/:slug/issuers/:slug/programs/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug + * **GET** /public/systems/:slug/issuers/:slug/programs/:slug * Badges * Managing: Badges can belong directly to a system, an issuer, or a program. * **GET** /systems/:slug/badges @@ -35,9 +38,6 @@ * **DELETE** /systems/:slug/issuers/:slug/badges/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug * Claim Codes - * **GET** /systems/:slug/codes - * **GET** /systems/:slug/issuers/:slug/codes - * **GET** /systems/:slug/issuers/:slug/programs/:slug/codes * **GET** /systems/:slug/codes/:code * **GET** /systems/:slug/issuers/:slug/codes/:code * **GET** /systems/:slug/issuers/:slug/programs/:slug/codes/:code @@ -59,9 +59,6 @@ * **POST** /systems/:slug/badges/:slug/codes/:code/claim * **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim - * **POST** /systems/:slug/badges/:slug/codes/:code/unclaim - * **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/:code/unclaim - * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/unclaim * Issuing * **GET** /systems/:slug/instances/:email * **GET** /systems/:slug/issuers/:slug/instances/:email @@ -78,6 +75,7 @@ * **DELETE** /systems/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email + * **GET** /public/assertions/:slug * Assessment * **GET** /systems/:slug/applications * **GET** /systems/:slug/issuers/:slug/applications @@ -88,30 +86,35 @@ * **POST** /systems/:slug/badges/:slug/applications * **POST** /systems/:slug/issuers/:slug/badges/:slug/applications * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications - * **GET** /systems/:slug/badges/:slug/applications/:id - * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:id - * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id - * **GET** /systems/:slug/badges/:slug/applications/:id/evidence - * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/evidence - * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/evidence - * **POST** /systems/:slug/badges/:slug/applications/:id/evidence - * **POST** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/evidence - * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/evidence - * **GET** /systems/:slug/badges/:slug/applications/:id/evidence/:id - * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/evidence/:id - * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/evidence/:id - * **DELETE** /systems/:slug/badges/:slug/applications/:id/evidence/:id - * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/evidence/:id - * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/evidence/:id - * **GET** /systems/:slug/badges/:slug/applications/:id/reviews/:id - * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/reviews/:id - * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/reviews/:id - * **POST** /systems/:slug/badges/:slug/applications/:id/reviews - * **POST** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/reviews - * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/reviews - * **PUT** /systems/:slug/badges/:slug/applications/:id/reviews/:id - * **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/reviews/:id - * **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/reviews/:id - * **DELETE** /systems/:slug/badges/:slug/applications/:id/reviews/:id - * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:id/reviews/:id - * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:id/reviews/:id + * **PUT** /systems/:slug/badges/:slug/applications/:slug + * **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug + * **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug + * **GET** /systems/:slug/badges/:slug/applications/:slug + * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug + * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug + * **DELETE** /systems/:slug/badges/:slug/applications/:slug + * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug + * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug + * **GET** /systems/:slug/badges/:slug/applications/:slug/reviews + * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews + * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews + * **GET** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug + * **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug + * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug + * **POST** /systems/:slug/badges/:slug/applications/:slug/reviews + * **POST** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews + * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews + * **PUT** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug + * **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug + * **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug + * **DELETE** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug + * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug + * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug + * Images + * **GET** /public/images/:imageId + * Milestones + * **GET** /systems/:slug/milestones + * **POST** /systems/:slug/milestones + * **GET** /systems/:slug/milestones/:milestoneId + * **PUT** /systems/:slug/milestones/:milestoneId + * **DELETE** /systems/:slug/milestones/:milestoneId From ec55a4f98ab0b0e286ca593d171f942365e5a2c8 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 21 May 2014 19:45:01 +0100 Subject: [PATCH 02/61] Alters endpoint category names to reflect routes. Adds explanatory info to category names. --- docs/api-endpoints.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index 29932e4..9e50bd9 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -20,8 +20,8 @@ * **PUT** /systems/:slug/issuers/:slug/programs/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug * **GET** /public/systems/:slug/issuers/:slug/programs/:slug -* Badges - * Managing: Badges can belong directly to a system, an issuer, or a program. +* Badge Management + * Badges (can belong directly to a system, issuer or program) * **GET** /systems/:slug/badges * **GET** /systems/:slug/issuers/:slug/badges * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges @@ -59,7 +59,7 @@ * **POST** /systems/:slug/badges/:slug/codes/:code/claim * **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim - * Issuing + * Issuing (badge instances) * **GET** /systems/:slug/instances/:email * **GET** /systems/:slug/issuers/:slug/instances/:email * **GET** /systems/:slug/issuers/:slug/programs/:slug/instances/:email @@ -76,7 +76,7 @@ * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email * **GET** /public/assertions/:slug - * Assessment + * Assessment (managing earner applications for badges) * **GET** /systems/:slug/applications * **GET** /systems/:slug/issuers/:slug/applications * **GET** /systems/:slug/issuers/:slug/programs/:slug/applications From 2d132ba2374273382e2ccc7cfbb0b5f2fd2b3871 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 21 May 2014 19:59:07 +0100 Subject: [PATCH 03/61] Create claim-codes.md Initial commit listing endpoints - to be fleshed out. --- docs/claim-codes.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/claim-codes.md diff --git a/docs/claim-codes.md b/docs/claim-codes.md new file mode 100644 index 0000000..9360ed1 --- /dev/null +++ b/docs/claim-codes.md @@ -0,0 +1,23 @@ +# Claim Codes + +* **GET** /systems/:slug/codes/:code +* **GET** /systems/:slug/issuers/:slug/codes/:code +* **GET** /systems/:slug/issuers/:slug/programs/:slug/codes/:code +* **GET** /systems/:slug/badges/:slug/codes +* **GET** /systems/:slug/issuers/:slug/badges/:slug/codes +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes +* **POST** /systems/:slug/badges/:slug/codes +* **POST** /systems/:slug/issuers/:slug/badges/:slug/codes +* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes +* **POST** /systems/:slug/badges/:slug/codes/random +* **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/random +* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/random +* **GET** /systems/:slug/badges/:slug/codes/:code +* **GET** /systems/:slug/issuers/:slug/badges/:slug/codes/:code +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code +* **DELETE** /systems/:slug/badges/:slug/codes/:code +* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/codes/:code +* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code +* **POST** /systems/:slug/badges/:slug/codes/:code/claim +* **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim +* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim From 57bdf3015fb7e558f2ca712b93e415d333441970 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 21 May 2014 20:00:30 +0100 Subject: [PATCH 04/61] Create issuing.md Initial commit lists endpoints - more info to come. --- docs/issuing.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/issuing.md diff --git a/docs/issuing.md b/docs/issuing.md new file mode 100644 index 0000000..f332a12 --- /dev/null +++ b/docs/issuing.md @@ -0,0 +1,18 @@ +# Issuing + +* **GET** /systems/:slug/instances/:email +* **GET** /systems/:slug/issuers/:slug/instances/:email +* **GET** /systems/:slug/issuers/:slug/programs/:slug/instances/:email +* **GET** /systems/:slug/badges/:slug/instances +* **GET** /systems/:slug/issuers/:slug/badges/:slug/instances +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances +* **GET** /systems/:slug/badges/:slug/instances/:email +* **GET** /systems/:slug/issuers/:slug/badges/:slug/instances/:email +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email +* **POST** /systems/:slug/badges/:slug/instances +* **POST** /systems/:slug/issuers/:slug/badges/:slug/instances +* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances +* **DELETE** /systems/:slug/badges/:slug/instances/:email +* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email +* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email +* **GET** /public/assertions/:slug From 84a27504fc57d62a0c87503cceac1966521546e8 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 21 May 2014 20:02:03 +0100 Subject: [PATCH 05/61] Create assessment.md Initial commit lists endpoints - more info coming. --- docs/assessment.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/assessment.md diff --git a/docs/assessment.md b/docs/assessment.md new file mode 100644 index 0000000..a0ce3d8 --- /dev/null +++ b/docs/assessment.md @@ -0,0 +1,35 @@ +# Assessment + +* **GET** /systems/:slug/applications +* **GET** /systems/:slug/issuers/:slug/applications +* **GET** /systems/:slug/issuers/:slug/programs/:slug/applications +* **GET** /systems/:slug/badges/:slug/applications +* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications +* **POST** /systems/:slug/badges/:slug/applications +* **POST** /systems/:slug/issuers/:slug/badges/:slug/applications +* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications +* **PUT** /systems/:slug/badges/:slug/applications/:slug +* **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug +* **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug +* **GET** /systems/:slug/badges/:slug/applications/:slug +* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug +* **DELETE** /systems/:slug/badges/:slug/applications/:slug +* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug +* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug +* **GET** /systems/:slug/badges/:slug/applications/:slug/reviews +* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews +* **GET** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug +* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug +* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug +* **POST** /systems/:slug/badges/:slug/applications/:slug/reviews +* **POST** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews +* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews +* **PUT** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug +* **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug +* **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug +* **DELETE** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug +* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug +* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug From a0eb042301f1a12e52b7b625a75bd11ec457b0a1 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 21 May 2014 21:36:39 +0100 Subject: [PATCH 06/61] Update systems.md Starts updating (GET endpoints). --- docs/systems.md | 96 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 80 insertions(+), 16 deletions(-) diff --git a/docs/systems.md b/docs/systems.md index b9a7309..46d8271 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -2,7 +2,7 @@ ## `GET /systems` -Retrieves all available systems. +Retrieves all available systems in the BadgeKit API instance. ### Expected request @@ -15,14 +15,43 @@ GET /systems HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "systems": [ - { - "name": "System Name", - "slug": "system-slug", - "description": "System description" - }, + { + "id": 1, + "slug": "system-slug", + "url": "http://systemsite.com", + "name": "System Name", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ + { + "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": [ + { + "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" + }, + ... + ] + }, + ... + ] + }, ... ] } @@ -47,12 +76,41 @@ GET /systems/ HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "system": { - "name": "System Name", + "id": 1, "slug": "system-slug", - "description": "System Description" + "url": "http://systemsite.com", + "name": "System Name", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ + { + "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": [ + { + "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" + }, + ... + ] + }, + ... + ] } } ``` @@ -61,15 +119,17 @@ Content-Type: application/json * **System not found** - ``` - HTTP/1.1 404 Not Found - Content-Type: application/json +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` - { - "code": "ResourceNotFound", - "message": "Could not find system with slug ``" - } - ``` +```json +{ + "code": "ResourceNotFound", + "message": "Could not find system field: `slug`, value: " +} +``` ## `POST /systems` @@ -260,3 +320,7 @@ Content-Type: application/json "message": "Could not find system with slug ``" } ``` + +## `GET /public/systems/` + +Retrieves a specific public system. From a8790793a0f59fed5d12c5ba27235cc559417463 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 22 May 2014 15:24:59 +0100 Subject: [PATCH 07/61] Update systems.md Still to do GET `public`. --- docs/systems.md | 132 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 104 insertions(+), 28 deletions(-) diff --git a/docs/systems.md b/docs/systems.md index 46d8271..285eb19 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -1,5 +1,17 @@ # Systems +A system represents the top admin level within BadgeKit - an instance can contain one or more systems, a system can contain one or more issuers and an issuer can contain one or more programs. All BadgeKit API needs to function is one system, which badges will be automatically included in. Badges can optionally be associated with a system, issuer or program. + +| NAME | VALUE | +|:---|:---| +| `id` | integer - _id from database entry_ | +| `slug` | string - _used to identify system in API endpoints_ | +| `url` | string | +| `name` | string | +| `email` | string | +| `imageUrl` | string | +| `issuers` | array - _[issuers](issuers.md) in the system (may contain [programs](programs.md))_ | + ## `GET /systems` Retrieves all available systems in the BadgeKit API instance. @@ -57,13 +69,25 @@ Content-Type: application/json } ``` +#### Response structure + +* systems `[ ]` + * id + * slug + * url + * name + * email + * imageUrl + * [issuers](issuers.md) `[ ]` + * [programs](programs.md) `[ ]` + ### Potential errors *None* ## `GET /systems/` -Retrieves a specific system. +Retrieves a specific system using its slug. ### Expected request @@ -115,6 +139,18 @@ Content-Type: application/json } ``` +#### Response structure + +* system + * id + * slug + * url + * name + * email + * imageUrl + * [issuers](issuers.md) `[ ]` + * [programs](programs.md) `[ ]` + ### Potential errors * **System not found** @@ -139,9 +175,6 @@ Creates a new system. Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. - - - | Parameters | Required | Description | |:-----------------------|-----------------|-------------------------| | **slug** | required | Short, computer-friendly name for the system. Good slugs are lowercase and use dashes instead of spaces, e.g. `city-of-chicago`. Maximum of 50 characters and each system must have a unique slug. @@ -156,27 +189,45 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` ``` HTTP/1.1 201 Created Content-Type: application/json +``` +```json { "status": "created", "system": { + "id": 1, "slug": "system-slug", "name": "System Name", - "url": "https://example.org/system/", - "email": "system-badges@example.org", - "description": "System Description" + "url": "http://systemsite.com", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] } } ``` +#### Response structure + +* status + * system + * id + * slug + * name + * url + * email + * imageUrl + * issuers `[ ]` + ### Potential errors * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -189,22 +240,24 @@ Content-Type: application/json ... ] } - ``` +``` * **Duplicate entry** - ``` +``` HTTP/1.1 409 Conflict Content-Type: application/json +``` +```json { "code": "ResourceConflict", "error": system with that `slug` already exists", "details": { "slug": "system-slug", "name": "System Name", - "url": "https://example.org/system/", - "email": "system-badges@example.org", + "url": "http://systemsite.com", + "email": "admin@systemsite.com", "description": "System Description" } } @@ -218,22 +271,35 @@ Updates an existing system. Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. -See above for parameters. You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. +| Parameters | Required | Description | +|:-----------------------|-----------------|-------------------------| +| **slug** | required | Short, computer-friendly name for the system. Good slugs are lowercase and use dashes instead of spaces, e.g. `city-of-chicago`. Maximum of 50 characters and each system must have a unique slug. +| **name** | required | Name of the system. Maximum of 255 characters. +| **url** | required | URL for the system. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. +| **description** | optional | A short, human-friendly description of the system. Maximum of 255 characters +| **email** | optional | Email address associated with the badge administrator of the system. +| **image** | optional | Image for the system. Should be either multipart data or a URL. + +You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. ### Expected response ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "updated", "system": { + "id": 1, "slug": "system-slug", - "name": Updated System Name", - "url": "https://example.org/system/", - "email": "system-badges@example.org", - "description": "Updated System Description" + "name": "System Name", + "url": "http://systemsite.com", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] } } ``` @@ -242,10 +308,12 @@ Content-Type: application/json * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -258,26 +326,28 @@ Content-Type: application/json ... ] } - ``` +``` * **Duplicate entry** - ``` +``` HTTP/1.1 409 Conflict Content-Type: application/json +``` +```json { "code": "ResourceConflict", "error": "system with that `slug` already exists", "details": { "slug": "system-slug", "name": "System Name", - "url": "https://example.org/system/", - "email": "system-badges@example.org", + "url": "http://systemsite.com", + "email": "admin@systemsite.com", "description": "System Description" } } - ``` +``` ## `DELETE /systems/` @@ -294,15 +364,19 @@ DELETE /systems/ HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "deleted", "system": { + "id": 1, "slug": "system-slug", "name": "System Name", - "url": "https://example.org/system/", - "email": "system-badges@example.org", - "description": "System Description" + "url": "http://systemsite.com", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] } } ``` @@ -311,15 +385,17 @@ Content-Type: application/json * **System not found** - ``` +``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", "message": "Could not find system with slug ``" } - ``` +``` ## `GET /public/systems/` From 4cdf37938f5db659fc301255f032a2cea64f5e69 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 22 May 2014 15:55:04 +0100 Subject: [PATCH 08/61] Update systems.md Adds TOC-type shortcuts at top. --- docs/systems.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/systems.md b/docs/systems.md index 285eb19..9510ab3 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -12,6 +12,14 @@ A system represents the top admin level within BadgeKit - an instance can contai | `imageUrl` | string | | `issuers` | array - _[issuers](issuers.md) in the system (may contain [programs](programs.md))_ | +## Endpoints + +* [`GET /systems`](#get-systems) +* [`GET /systems/`](#get-systemsslug) +* [`POST /systems`](#post-systems) +* [`PUT /systems/`](#put-systemsslug) +* [`DELETE /systems/`](#delete-systemsslug) + ## `GET /systems` Retrieves all available systems in the BadgeKit API instance. @@ -252,7 +260,7 @@ Content-Type: application/json ```json { "code": "ResourceConflict", - "error": system with that `slug` already exists", + "error": "system with that `slug` already exists", "details": { "slug": "system-slug", "name": "System Name", From 00efb1ea517365c5847b0aca92a08b206d51d030 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 23 May 2014 18:34:36 +0100 Subject: [PATCH 09/61] Update api-endpoints.md Links to other docs, adds intro. --- docs/api-endpoints.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index 9e50bd9..53204e2 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -1,19 +1,23 @@ +# API Endpoints + +See the following overview of the available BadgeKit API endpoints - browse to the linked docs for each object/ process for more detailed information. + * Containers - * Systems + * [Systems](systems.md) * **GET** /systems * **POST** /systems * **GET** /systems/:slug * **PUT** /systems/:slug * **DELETE** /systems/:slug * **GET** /public/systems/:slug - * Issuers + * [Issuers](issuers.md) * **GET** /systems/:slug/issuers * **POST** /systems/:slug/issuers * **GET** /systems/:slug/issuers/:slug * **PUT** /systems/:slug/issuers/:slug * **DELETE** /systems/:slug/issuers/:slug * **GET** /public/systems/:slug/issuers/:slug - * Programs + * [Programs](programs.md) * **GET** /systems/:slug/issuers/:slug/programs * **POST** /systems/:slug/issuers/:slug/programs * **GET** /systems/:slug/issuers/:slug/programs/:slug @@ -21,7 +25,7 @@ * **DELETE** /systems/:slug/issuers/:slug/programs/:slug * **GET** /public/systems/:slug/issuers/:slug/programs/:slug * Badge Management - * Badges (can belong directly to a system, issuer or program) + * [Badges](badges.md) (can belong directly to a system, issuer or program) * **GET** /systems/:slug/badges * **GET** /systems/:slug/issuers/:slug/badges * **GET** /systems/:slug/issuers/:slug/programs/:slug/badges @@ -37,7 +41,7 @@ * **DELETE** /systems/:slug/badges/:slug * **DELETE** /systems/:slug/issuers/:slug/badges/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug - * Claim Codes + * [Claim Codes](claim-codes.md) * **GET** /systems/:slug/codes/:code * **GET** /systems/:slug/issuers/:slug/codes/:code * **GET** /systems/:slug/issuers/:slug/programs/:slug/codes/:code @@ -59,7 +63,7 @@ * **POST** /systems/:slug/badges/:slug/codes/:code/claim * **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim - * Issuing (badge instances) + * [Issuing](issuing.md) (badge instances) * **GET** /systems/:slug/instances/:email * **GET** /systems/:slug/issuers/:slug/instances/:email * **GET** /systems/:slug/issuers/:slug/programs/:slug/instances/:email @@ -76,7 +80,7 @@ * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email * **GET** /public/assertions/:slug - * Assessment (managing earner applications for badges) + * [Assessment](#assessment) (managing earner applications for badges) * **GET** /systems/:slug/applications * **GET** /systems/:slug/issuers/:slug/applications * **GET** /systems/:slug/issuers/:slug/programs/:slug/applications @@ -118,3 +122,5 @@ * **GET** /systems/:slug/milestones/:milestoneId * **PUT** /systems/:slug/milestones/:milestoneId * **DELETE** /systems/:slug/milestones/:milestoneId + +See also [authorization](authorization.md) and [webhooks](webhooks.md). From d10683d611c093c2ad14518417a309028bfea365 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 23 May 2014 18:35:56 +0100 Subject: [PATCH 10/61] Update api-endpoints.md --- docs/api-endpoints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index 53204e2..988ee4f 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -80,7 +80,7 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email * **GET** /public/assertions/:slug - * [Assessment](#assessment) (managing earner applications for badges) + * [Assessment](assessment.md) (managing earner applications for badges) * **GET** /systems/:slug/applications * **GET** /systems/:slug/issuers/:slug/applications * **GET** /systems/:slug/issuers/:slug/programs/:slug/applications From 9ec91fc98c110da154eeee83efe0e29681fbe467 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 23 May 2014 18:48:35 +0100 Subject: [PATCH 11/61] Create README.md Initial readme for docs directory. --- docs/README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..facb76b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# BadgeKit API Documentation + +The BadgeKit API docs include the information you need to get started using the endpoints and webhooks. The docs are as follows: + +* [API Endpoints](api-endpoints.md) + * Containers: + * [Systems](systems.md) + * [Issuers](issuers.md) + * [Programs](programs.md) + * Badge Management: + * [Badges](badges.md) + * [Claim Codes](claim-codes.md) + * [Issuing](issuing.md) + * [Assessment](assessment.md) +* [Webhooks](webhooks.md) +* [Authorization](authorization.md) + +You will also find detailed guides to carrying out common processes, together with sample code excerpts, in the [BadgeKit API wiki](https://github.com/mozilla/badgekit-api/wiki): + +* [Using BadgeKit API](https://github.com/mozilla/badgekit-api/wiki/Using-BadgeKit-API) +* [Retrieving Badges](https://github.com/mozilla/badgekit-api/wiki/Retrieving-Badges) +* [Submitting Applications](https://github.com/mozilla/badgekit-api/wiki/Submitting-Applications) +* [Application Review Webhooks](https://github.com/mozilla/badgekit-api/wiki/Application-Review-Webhooks) +* [Awarding Badges](https://github.com/mozilla/badgekit-api/wiki/Awarding-Badges) +* [Badge Issued Webhooks](https://github.com/mozilla/badgekit-api/wiki/Badge-Issued-Webhooks) + +If you have any problems using BadgeKit or the API, feel free to get in touch using one of the following methods: + +* Post general questions in our [Community Google Groups](http://bit.ly/OBIGeneral) and post technical questions in our [Dev Google Group](http://bit.ly/OBIDev). +* Reach members of the Open Badges team directly on IRC (irc.mozilla.org) on the #badges channel. +* Email questions directly to [badges@mozillafoundation.org](mailto:badges@mozillafoundation.org) and a member of the team will follow-up. +* Follow or tweet the Open Badges team [@OpenBadges](https://twitter.com/OpenBadges). +* Get involved or submit issues via the GitHub repos - feedback is always appreciated! From 531464b4ccc39e0b7b42df2216c2ca8c6c438aaa Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 23 May 2014 18:56:39 +0100 Subject: [PATCH 12/61] Update README.md --- docs/README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/README.md b/docs/README.md index facb76b..3b61fa9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,18 +4,20 @@ The BadgeKit API docs include the information you need to get started using the * [API Endpoints](api-endpoints.md) * Containers: - * [Systems](systems.md) - * [Issuers](issuers.md) - * [Programs](programs.md) + * [Systems](systems.md) + * [Issuers](issuers.md) + * [Programs](programs.md) * Badge Management: - * [Badges](badges.md) - * [Claim Codes](claim-codes.md) - * [Issuing](issuing.md) - * [Assessment](assessment.md) + * [Badges](badges.md) + * [Claim Codes](claim-codes.md) + * [Issuing](issuing.md) + * [Assessment](assessment.md) * [Webhooks](webhooks.md) * [Authorization](authorization.md) -You will also find detailed guides to carrying out common processes, together with sample code excerpts, in the [BadgeKit API wiki](https://github.com/mozilla/badgekit-api/wiki): +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 it 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. + +The API docs provide a reference for the endpoints and webhooks. You will also find detailed guides to carrying out common processes, together with sample code excerpts, in the [BadgeKit API wiki](https://github.com/mozilla/badgekit-api/wiki): * [Using BadgeKit API](https://github.com/mozilla/badgekit-api/wiki/Using-BadgeKit-API) * [Retrieving Badges](https://github.com/mozilla/badgekit-api/wiki/Retrieving-Badges) @@ -24,7 +26,7 @@ You will also find detailed guides to carrying out common processes, together wi * [Awarding Badges](https://github.com/mozilla/badgekit-api/wiki/Awarding-Badges) * [Badge Issued Webhooks](https://github.com/mozilla/badgekit-api/wiki/Badge-Issued-Webhooks) -If you have any problems using BadgeKit or the API, feel free to get in touch using one of the following methods: +For additional support using BadgeKit or the API, feel free to get in touch using one of the following methods: * Post general questions in our [Community Google Groups](http://bit.ly/OBIGeneral) and post technical questions in our [Dev Google Group](http://bit.ly/OBIDev). * Reach members of the Open Badges team directly on IRC (irc.mozilla.org) on the #badges channel. From 671aca7a6692bc86aa93630effae85b7bbd01e5e Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Mon, 26 May 2014 22:11:53 +0100 Subject: [PATCH 13/61] Update issuers.md First pass through issuer endpoints. --- docs/issuers.md | 234 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 188 insertions(+), 46 deletions(-) diff --git a/docs/issuers.md b/docs/issuers.md index 4835c1c..8f17b30 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -1,8 +1,29 @@ # Issuers -## Retrieve list of issuers +Issuers represent mid-level admin in BadgeKit. Each issuer belongs to a single [system](system.md), optionally along with other issuers. An issuer can contain one or more [programs](programs.md). Badges can be associated with an issuer, which will typically be a single organization within a badging system, such as a library, museum or school. -Retrieves all available issuers, filtered by system. +| NAME | VALUE | +|:---|:---| +| `id` | integer - _id from database entry_ | +| `slug` | string - _used to identify issuer in API endpoints_ | +| `url` | string | +| `name` | string | +| `description` | string | +| `email` | string | +| `imageUrl` | string | +| `programs` | array - _[programs](programs.md) in the issuer_ | + +## Endpoints + +* [`GET /systems//issuers`](#get-issuers) +* [`POST /systems//issuers`](#post-issuers) +* [`GET /systems//issuers/`](#get-systemsslugissuersslug) +* [`PUT /systems//issuers/`](#put-systemsslugissuersslug) +* [`DELETE /systems//issuers/`](#delete-systemsslugissuersslug) + +## `GET /systems//issuers` + +Retrieves all available issuers in the specified system. ### Expected request @@ -15,26 +36,56 @@ GET /systems/:systemSlug/issuers HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "issuers": [ { - "name": "Issuer Name", + "id": 1, "slug": "issuer-slug", - "description": "Issuer description" + "url": "http://issuersite.com", + "name": "Issuer Name", + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ + { + "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" + }, + ... + ] }, ... ] } ``` +#### Response structure + +* issuers `[ ]` + * id + * slug + * url + * name + * description + * email + * imageUrl + * [programs](programs.md) `[ ]` + ### Potential errors *None* -## Retrieve a specific issuer +## `GET /systems//issuers/` -Retrieves a specific issuer. +Retrieves a specific issuer using its slug. ### Expected request @@ -47,43 +98,74 @@ GET /systems/:systemSlug/issuers/:issuerSlug HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "issuer": { - "name": "Issuer Name", + "id": 1, "slug": "issuer-slug", - "description": "Issuer Description" + "url": "http://issuersite.com", + "name": "Issuer Name", + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ + { + "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" + }, + ... + ] } } ``` +#### Response structure + +* issuer + * id + * slug + * url + * name + * description + * email + * imageUrl + * [programs](programs.md) `[ ]` + ### Potential errors * **Issuer not found** - ``` +``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", - "message": "Could not find issuer with slug ``" + "message": "Could not find issuer field: `slug`, value ``" } - ``` +``` -## Create a new issuer +## `POST /systems//issuers` Creates a new issuer. ### Expected request -`/systems/:systemSlug/issuers/:issuerSlug` +``` +POST /systems/:systemSlug/issuers` +``` Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. - - - | Parameters | Required | Description | |:-----------------------|-----------------|-------------------------| | **slug** | required | Short, computer-friendly name for the issuer. Good slugs are lowercase and use dashes instead of spaces, e.g. `chicago-public-library`. Maximum of 50 characters and each issuer must have a unique slug. @@ -98,27 +180,58 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` ``` HTTP/1.1 201 Created Content-Type: application/json +``` +```json { "status": "created", "issuer": { + "id": 1, "slug": "issuer-slug", + "url": "http://issuersite.com", "name": "Issuer Name", - "url": "https://example.org/issuer/", - "email": "issuer-badges@example.org", - "description": "Issuer Description" + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ + { + "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" + }, + ... + ] } } ``` +#### Response structure + +* status + * issuer + * id + * slug + * url + * name + * description + * email + * imageUrl + * programs `[ ]` + ### Potential errors * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -131,53 +244,71 @@ Content-Type: application/json ... ] } - ``` +``` * **Duplicate entry** - ``` +``` HTTP/1.1 409 Conflict Content-Type: application/json +``` +```json { "code": "ResourceConflict", "error": issuer with that `slug` already exists", "details": { "slug": "issuer-slug", "name": "Issuer Name", - "url": "https://example.org/issuer/", - "email": "issuer-badges@example.org", - "description": "Issuer Description" + "url": "http://issuersite.com", + "email": "admin@issuersite.com", + "description": "Issuer description." } } - ``` +``` -## Update an issuer +## `PUT /systems//issuers/` Updates an existing issuer. ### Expected request -`PUT /systems/:systemSlug/issuers/:issuerSlug` +``` +PUT /systems/:systemSlug/issuers/:issuerSlug +``` Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. -See above for parameters. You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. +| Parameters | Required | Description | +|:-----------------------|-----------------|-------------------------| +| **slug** | required | Short, computer-friendly name for the issuer. Good slugs are lowercase and use dashes instead of spaces, e.g. `chicago-public-library`. Maximum of 50 characters and each issuer must have a unique slug. +| **name** | required | Name of the issuer. Maximum of 255 characters. +| **url** | required | URL for the issuer. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. +| **description** | optional | A short, human-friendly description of the issuer. Maximum of 255 characters +| **email** | optional | Email address associated with the badge administrator of the issuer. +| **image** | optional | Image for the issuer. Should be either multipart data or a URL. + +You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. ### Expected response ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "updated", "issuer": { + "id": 1, "slug": "issuer-slug", - "name": Updated Issuer Name", - "url": "https://example.org/issuer/", - "email": "issuer-badges@example.org", - "description": "Updated Issuer Description" + "url": "http://issuersite.com", + "name": "Updated Issuer Name", + "description": "Updated Issuer Description", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ ] } } ``` @@ -186,10 +317,12 @@ Content-Type: application/json * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -206,31 +339,33 @@ Content-Type: application/json * **Duplicate entry** - ``` +``` HTTP/1.1 409 Conflict Content-Type: application/json +``` +```json { "code": "ResourceConflict", "error": "issuer with that `slug` already exists", "details": { "slug": "issuer-slug", "name": "Issuer Name", - "url": "https://example.org/issuer/", - "email": "issuer-badges@example.org", - "description": "Issuer Description" + "url": "http://issuersite.com", + "email": "admin@issuersite.com", + "description": "Issuer description." } } ``` -## Delete an existing issuer +## `DELETE /systems//issuers/` Deletes an existing issuer. ### Expected request ``` -DELETE /system/:systemSlug/issuers/:issuerSlug HTTP/1.1 +DELETE /systems/:systemSlug/issuers/:issuerSlug HTTP/1.1 ``` ### Expected response @@ -238,15 +373,20 @@ DELETE /system/:systemSlug/issuers/:issuerSlug HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "deleted", "issuer": { + "id": 1, "slug": "issuer-slug", + "url": "http://issuersite.com", "name": "Issuer Name", - "url": "https://example.org/issuer/", - "email": "issuer-badges@example.org", - "description": "Issuer Description" + "description": "Issuer description.", + "email": "admin@issuersite.com", + "imageUrl": "http://issuersite.com/image.jpg", + "programs": [ ] } } ``` @@ -255,12 +395,14 @@ Content-Type: application/json * **Issuer not found** - ``` +``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", - "message": "Could not find issuer with slug ``" + "message": "Could not find issuer field: `slug`, value: ``" } - ``` +``` From 252cfb6fc2647a0520999c6e5acd3eab325a91b5 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Mon, 26 May 2014 22:16:11 +0100 Subject: [PATCH 14/61] Update issuers.md --- docs/issuers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/issuers.md b/docs/issuers.md index 8f17b30..b0ebcf2 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -1,6 +1,6 @@ # Issuers -Issuers represent mid-level admin in BadgeKit. Each issuer belongs to a single [system](system.md), optionally along with other issuers. An issuer can contain one or more [programs](programs.md). Badges can be associated with an issuer, which will typically be a single organization within a badging system, such as a library, museum or school. +Issuers represent mid-level admin in BadgeKit. Each issuer belongs to a single [system](systems.md), optionally along with other issuers. An issuer can contain one or more [programs](programs.md). Badges can be associated with an issuer, which will typically be a single organization within a badging system, such as a library, museum or school. | NAME | VALUE | |:---|:---| @@ -15,9 +15,9 @@ Issuers represent mid-level admin in BadgeKit. Each issuer belongs to a single [ ## Endpoints -* [`GET /systems//issuers`](#get-issuers) -* [`POST /systems//issuers`](#post-issuers) +* [`GET /systems//issuers`](#get-systemsslugissuers) * [`GET /systems//issuers/`](#get-systemsslugissuersslug) +* [`POST /systems//issuers`](#post-systemsslugissuers) * [`PUT /systems//issuers/`](#put-systemsslugissuersslug) * [`DELETE /systems//issuers/`](#delete-systemsslugissuersslug) @@ -256,7 +256,7 @@ Content-Type: application/json ```json { "code": "ResourceConflict", - "error": issuer with that `slug` already exists", + "error": "issuer with that `slug` already exists", "details": { "slug": "issuer-slug", "name": "Issuer Name", From 5d65e1458531453a8a9d8ed049ffcc5215e7717a Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Mon, 26 May 2014 22:21:27 +0100 Subject: [PATCH 15/61] Update systems.md --- docs/systems.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/systems.md b/docs/systems.md index 9510ab3..bb73f72 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -100,7 +100,7 @@ Retrieves a specific system using its slug. ### Expected request ``` -GET /systems/ HTTP/1.1 +GET /systems/:systemSlug HTTP/1.1 ``` ### Expected response @@ -181,6 +181,10 @@ Creates a new system. ### Expected request +``` +POST /systems +``` + Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. | Parameters | Required | Description | @@ -277,6 +281,10 @@ Updates an existing system. ### Expected request +``` +PUT /systems/:systemSlug +``` + Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. | Parameters | Required | Description | @@ -364,7 +372,7 @@ Deletes an existing system. ### Expected request ``` -DELETE /systems/ HTTP/1.1 +DELETE /systems/:systemSlug HTTP/1.1 ``` ### Expected response From 4d65af1a6a323502b02774c240b6ff886c6096c3 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Tue, 27 May 2014 14:15:38 +0100 Subject: [PATCH 16/61] Update programs.md First pass through programs endpoints. --- docs/programs.md | 186 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 140 insertions(+), 46 deletions(-) diff --git a/docs/programs.md b/docs/programs.md index 7919e87..5c0214c 100644 --- a/docs/programs.md +++ b/docs/programs.md @@ -1,8 +1,28 @@ # Programs -## Retrieve all programs, filtered by system and issuer. +Programs represent the last level of badging admin in BadgeKit. Each program belongs to one [issuer](issuers.md), optionally along with other programs. Badges can be associated with a program, which could be a program of events grouping activities on a theme or subject area. -Retrieves all available programs. +| NAME | VALUE | +|:---|:---| +| `id` | integer - _id from database entry_ | +| `slug` | string - _used to identify program in API endpoints_ | +| `url` | string | +| `name` | string | +| `description` | string | +| `email` | string | +| `imageUrl` | string | + +## Endpoints + +* [`GET /systems//issuers//programs`](#get-systemsslugissuersslugprograms) +* [`GET /systems//issuers//programs/`](#get-systemsslugissuersslugprogramsslug) +* [`POST /systems//issuers//programs`](#post-systemsslugissuersslugprograms) +* [`PUT /systems//issuers//programs/`](#put-systemsslugissuersslugprogramsslug) +* [`DELETE /systems//issuers//programs/`](#delete-systemsslugissuersslugprogramsslug) + +## `GET /systems//issuers//programs` + +Retrieves all available programs in the specified system and issuer. ### Expected request @@ -15,31 +35,47 @@ GET /systems/:systemSlug/issuers/:issuerSlug/programs HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "programs": [ { - "name": "Program Name", + "id": 1, "slug": "program-slug", - "description": "Program description" + "url": "http://programsite.com", + "name": "Program Name", + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" }, ... ] } ``` +#### Response structure + +* programs `[ ]` + * id + * slug + * url + * name + * description + * email + * imageUrl ### Potential errors *None* -## Retrieve a specific program +## `GET /systems//issuers//programs/` -Retrieves a specific program. +Retrieves a specific program using its slug. ### Expected request ``` -GET /systems/:systemSlug/issuers/:issuerSlug/programs/ HTTP/1.1 +GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 ``` ### Expected response @@ -47,31 +83,50 @@ GET /systems/:systemSlug/issuers/:issuerSlug/programs/ HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "program": { - "name": "Program Name", + "id": 1, "slug": "program-slug", - "description": "Program Description" + "url": "http://programsite.com", + "name": "Program Name", + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" } } ``` +#### Response structure + +* program + * id + * slug + * url + * name + * description + * email + * imageUrl + ### Potential errors * **Program not found** - ``` +``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", - "message": "Could not find program with slug ``" + "message": "Could not find program field: `slug`, value: ``" } - ``` +``` -## Create a new program +## `POST /systems//issuers//programs` Creates a new program. @@ -83,9 +138,6 @@ POST /systems/:systemSlug/issuers/:issuerSlug/programs HTTP/1.1 Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. - - - | Parameters | Required | Description | |:-----------------------|-----------------|-------------------------| | **slug** | required | Short, computer-friendly name for the program. Good slugs are lowercase and use dashes instead of spaces, e.g. `cpl-rahms-readers`. Maximum of 50 characters and each program must have a unique slug. @@ -100,27 +152,45 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` ``` HTTP/1.1 201 Created Content-Type: application/json +``` +```json { "status": "created", "program": { + "id": 1, "slug": "program-slug", + "url": "http://programsite.com", "name": "Program Name", - "url": "https://example.org/program/", - "email": "program-badges@example.org", - "description": "Program Description" + "description": "Program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" } } ``` +#### Response structure + +* status +* program + * id + * slug + * url + * name + * description + * email + * imageUrl + ### Potential errors * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -133,28 +203,30 @@ Content-Type: application/json ... ] } - ``` +``` * **Duplicate entry** - ``` +``` HTTP/1.1 409 Conflict Content-Type: application/json +``` +```json { "code": "ResourceConflict", - "error": program with that `slug` already exists", + "error": "program with that `slug` already exists", "details": { "slug": "program-slug", "name": "Program Name", - "url": "https://example.org/program/", - "email": "program-badges@example.org", - "description": "Program Description" + "url": "http://programsite.com", + "email": "admin@programsite.com", + "description": "Program description." } } - ``` +``` -## Update an existing program +## `PUT /systems//issuers//programs/` Updates an existing program. @@ -163,24 +235,38 @@ Updates an existing program. ``` PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 ``` + Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. -See above for parameters. You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. +| Parameters | Required | Description | +|:-----------------------|-----------------|-------------------------| +| **slug** | required | Short, computer-friendly name for the program. Good slugs are lowercase and use dashes instead of spaces, e.g. `cpl-rahms-readers`. Maximum of 50 characters and each program must have a unique slug. +| **name** | required | Name of the program. Maximum of 255 characters. +| **url** | required | URL for the program. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. +| **description** | optional | A short, human-friendly description of the program. Maximum of 255 characters +| **email** | optional | Email address associated with the badge administrator of the program. +| **image** | optional | Image for the program. Should be either multipart data or a URL. + +You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. ### Expected response ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "updated", "program": { + "id": 1, "slug": "program-slug", + "url": "http://programsite.com", "name": Updated Program Name", - "url": "https://example.org/program/", - "email": "program-badges@example.org", - "description": "Updated Program Description" + "description": "Updated program description.", + "email": "admin@programsite.com", + "imageUrl": "http://programsite.com/image.jpg" } } ``` @@ -189,10 +275,12 @@ Content-Type: application/json * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -205,28 +293,30 @@ Content-Type: application/json ... ] } - ``` +``` * **Duplicate entry** - ``` +``` HTTP/1.1 409 Conflict Content-Type: application/json +``` +```json { "code": "ResourceConflict", "error": "program with that `slug` already exists", "details": { "slug": "program-slug", "name": "Program Name", - "url": "https://example.org/program/", - "email": "program-badges@example.org", - "description": "Program Description" + "url": "http://programsite.com", + "email": "admin@programsite.com", + "description": "Program description." } } - ``` +``` -## Delete a program +## `DELETE /systems//issuers//programs/` Deletes an existing program. @@ -241,15 +331,17 @@ DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "deleted", "program": { "slug": "program-slug", "name": "Program Name", - "url": "https://example.org/program/", - "email": "program-badges@example.org", - "description": "Program Description" + "url": "http://programsite.com", + "email": "admin@programsite.com", + "description": "Program description." } } ``` @@ -258,12 +350,14 @@ Content-Type: application/json * **Program not found** - ``` +``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", - "message": "Could not find program with slug ``" + "message": "Could not find program field: `slug`, value: ``" } - ``` +``` From 8c813fe8e7c30e66253478ba76be2218d4e083fe Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Tue, 27 May 2014 17:15:06 +0100 Subject: [PATCH 17/61] Update badges.md Starting to work through badges endpoints. --- docs/badges.md | 149 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 132 insertions(+), 17 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index a02c06e..1c8422f 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -1,6 +1,56 @@ # Badges -## `Badge List` +A badge represents the generic data for an earnable badge (not an awarded badge, which is a [badge instance](issuing.md)). Badges can be published or archived. Each badge can belong to a [system](systems.md), [issuer](issuers.md) or [program](programs.md). + +| NAME | VALUE | +|:---|:---| +| `id` | integer - _id from database entry_ | +| `slug` | string - _used to identify badge in API endpoints_ | +| `name` | string | +| `strapline` | string - _Short tagline description._ | +| `earnerDescription` | string - _Description for potential earners._ | +| `consumerDescription` | string - _Description for viewers of badge e.g. college admin or employer._ | +| `issuerUrl` | string | +| `rubricUrl` | string - _Link to supporting material._ | +| `timeValue` | integer | +| `timeUnits` | _Can be `minutes`, `hours`, `days` or `weeks`._ | +| `limit` | integer - _Optional limit for number of times badge can be earned._ | +| `unique` | boolean | +| `created` | timestamp | +| `imageUrl` | string | +| `type` | string - _Can be automatically assigned in BadgeKit Web app._ | +| `archived` | boolean | +| `system` | _System is represented by ID in database - system details are returned from API endpoints as nested JSON._ | +| `criteriaUrl` | string | +| `criteria` | array - _Includes `id`, `description`, `required` status and `note`._ | +| `categories` | array | +| `tags` | array | +| `milestones` | array | + +## Endpoints + +* [Retrieve Badge List](#retrieve-badge-list) + * `GET /systems//badges` + * `GET /systems//issuers//badges` + * `GET /systems//issuers//programs//badges` +* [Retrieve Specific Badge](#retrieve-specific-badge) + * `GET /systems//badges/` + * `GET /systems//issuers//badges/` + * `GET /systems//issuers//programs/` +* [Create New Badge](#create-new-badge) + * `POST /systems//badges` + * `POST /systems//issuers//badges` + * `POST / systems//issuers//programs/` +* [Update a Badge](#update-a-badge) + * `PUT /systems//badges/` + * `PUT /systems//issuers//badges/` + * `PUT /systems//issuers//programs//badges/` +* [Delete a Badge](#delete-a-badge) + * `DELETE /systems//badges/` + * `DELETE /systems//issuers//badges/` + * `DELETE /systems//issuers//programs//badges/` + +## Retrieve Badge List Retrieves all available badges, filtered by system, issuer or program. @@ -14,8 +64,7 @@ GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/1 #### Available request parameters -* **`archived`:** `[true|false|any]` - Whether to include archived badges. +* **`archived`:** `[true|false|any]` (optional) - _Whether to include archived badges._ * `true` will return only archived badges * `false` (default) will return only unarchived badges * `any` will return badges regardless of archived status @@ -25,37 +74,101 @@ GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/1 ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "badges": [ { - "name": "Badge Name", + "id": 1, "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, + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Badge description for potential earners.", + "consumerDescription": "Badge description for interested consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, "timeUnits": "minutes", "limit": 5, "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badge.png", + "type": "badge type", + "archived": false, + "system": { + "id": 1, + "slug": "system-slug", + "url": "http://systemsite.com", + "name": "System Name", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] + } + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ + { + "id": 1, + "description": "Criteria description.", + "required": true, + "note": "Note about criteria for assessor." + }, + ... + ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] }, ... ] } ``` +#### Response structure + +* badges `[ ]` + * id + * slug + * name + * strapline + * earnerDescription + * consumerDescription + * issuerUrl + * rubricUrl + * timeValue + * timeUnits + * limit + * unique + * created + * imageUrl + * type + * archived + * system `[ ]` + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * criteriaUrl + * criteria `[ ]` + * id + * description + * required + * note + * categories `[ ]` + * tags `[ ]` + * milestones `[ ]` + + ### Potential errors *None* -## `Retrieve a specific badge` +## Retrieve Specific Badge -Retrieves a specific badge. +Retrieves a specific badge using its slug. ### Expected request @@ -105,7 +218,7 @@ Content-Type: application/json } ``` -## `Create a badge` +## `Create New Badge` Creates a new badge, or updates an existing badge. @@ -275,12 +388,14 @@ Content-Type: application/json } ``` -## `PUT /badges/` +## Update a Badge Updates an existing badge. ### Expected request +`PUT /badges/` + Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. ``` From f7e20f05ca12727d9141928a12c06d80313c5d3c Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Tue, 27 May 2014 17:20:11 +0100 Subject: [PATCH 18/61] Update issuers.md --- docs/issuers.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/issuers.md b/docs/issuers.md index b0ebcf2..7385cb1 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -212,15 +212,15 @@ Content-Type: application/json #### Response structure * status - * issuer - * id - * slug - * url - * name - * description - * email - * imageUrl - * programs `[ ]` +* issuer + * id + * slug + * url + * name + * description + * email + * imageUrl + * programs `[ ]` ### Potential errors @@ -313,6 +313,19 @@ Content-Type: application/json } ``` +#### Response structure + +* status +* issuer + * id + * slug + * url + * name + * description + * email + * imageUrl + * programs `[ ]` + ### Potential errors * **Invalid data** From 27e3a475ed60e6d8f3f5fbb1a65e89e4164f82da Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 17:45:52 +0100 Subject: [PATCH 19/61] Update badges.md --- docs/badges.md | 273 +++++++++++++++++++++++++++++++------------------ 1 file changed, 173 insertions(+), 100 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index 1c8422f..76ad0b7 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -183,44 +183,109 @@ GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badge ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "badge": { - "name": "Badge Name", + "id": 1, "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", + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Badge description for potential earners.", + "consumerDescription": "Badge description for consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", "timeValue": 10, "timeUnits": "minutes", "limit": 5, "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badge.png", + "type": "badge type", + "archived": false, + "system": { + "id": 1, + "slug": "system-slug", + "url": "http://systemsite.com", + "name": "System Name", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] + }, + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ + { + "id": 1, + "description": "criteria description", + "required": 1, + "note": "note for assessor" + }, + ... + ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] } } ``` +#### Response structure + +* badge + * id + * slug + * name + * strapline + * earnerDescription + * consumerDescription + * issuerUrl + * rubricUrl + * timeValue + * timeUnits + * limit + * unique + * created + * imageUrl + * type + * archived + * system `[ ]` + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * criteriaUrl + * criteria `[ ]` + * id + * description + * required + * note + * categories `[ ]` + * tags `[ ]` + * milestones `[ ]` + ### Potential errors * **Badge not found** - ``` + ``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", - "message": "Could not find badge with slug ``" + "message": "Could not find badge field: `slug`, value: ``" } - ``` +``` ## `Create New Badge` -Creates a new badge, or updates an existing badge. +Creates a new badge in a system, issuer or program (_or updates an existing badge_). ### Expected request @@ -232,112 +297,120 @@ POST /systems/:systemSlug/issuers/:issuerSlug/badges HTTP/1.1 POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges ``` -``` -HTTP/1.1 - -Content-Type: application/json - -{ - "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", - "limit": 5, - "unique": false, - "imageUrl": "http://example.org/image.png", - "archived": false -} -``` - -``` -Content-Type: application/x-www-form-urlencoded - -name=Badge%20Name&slug=badge-slug&strapline=Badge%20Strapline&description=Badge%20Description&imageUrl=http%3A%2F%2Fexample.org%2Fimage.png -``` - -``` -Content-Type: multipart/form-data; boundary=… - ---… -content-disposition: form-data; name="name" - -Badge Name ---… -content-disposition: form-data; name="slug" - -badge-slug ---… -content-disposition: form-data; name="strapline" - -Badge Strapline ---… -content-disposition: form-data; name="description" - -Badge Description ---… -content-disposition: form-data; name="imageUrl" - -http://example.org/image.png ---…-- -``` - -#### Alternatively… - -Images can be uploaded and hosted by the issuer API. - -``` -Content-Type: multipart/form-data; boundary=… - ---… -… ---… -content-disposition: form-data; name="image"; filename="…" -Content-Type: image/png -Content-Transfer-Encoding: binary - -… ---…-- -``` - -``` -Content-Type: application/x-www-form-urlencoded - -…&image=data%3Aimage%2Fpng%3Bbase64%2C… -``` +| 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. +| **strapline** | optional | Short tagline style description of the badge. Maximum 140 characters. +| **earnerDescription** | required | Description of the badge for potential earners. +| **consumerDescription** | required | Description of the badge for consumers viewing it. +| **type** | required | Short string representing badge type. Maximum 255 characters. +| **issuerUrl** | optional | URL for badge issuer. +| **rubricUrl** | optional | Link to any rubric material associated with the badge. +| **timeValue** | optional | Badges can be associated with a time limit for earning. +| **timeUnits** | optional | Time values can be expressed as `minutes`, `hours`, `days` or `weeks`. +| **earnerDescription** | required | Description of the badge for potential earners. +| **limit** | optional | Badges can be awarded to a fixed maximum number of earners. +| **unique** | optional | _boolean_ Badges can be unique. +| **image** OR **imageUrl** | required | Image for the program. Should be either multipart data or a URL. +| **archived** | optional | Boolean indicating archived status for badge. +| **criteriaUrl** | optional | Link to badge criteria. +| **criteria** | optional | Array of criteria items - each criteria should include `description` and `required` status plus optional `note` for badge reviewers. +| **categories** | optional | Array of category names for the badge. +| **tags** | optional | Array of tag names for the badge. +| **milestones** | optional | Array of [milestones](milestones.md). ### Expected response ``` HTTP/1.1 201 Created Content-Type: application/json +``` +```json { "status": "created", "badge": { - "name": "Badge Name", + "id": 1, "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", + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Badge description for potential earners.", + "consumerDescription": "Badge description for consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", "timeValue": 10, "timeUnits": "minutes", "limit": 5, "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badge.png", + "type": "badge type", + "archived": false, + "system": { + "id": 1, + "slug": "system-slug", + "url": "http://systemsite.com", + "name": "System Name", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] + }, + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ + { + "id": 1, + "description": "criteria description", + "required": 1, + "note": "note for assessor" + }, + ... + ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] } } ``` +#### Response structure + +* status +* badge + * id + * slug + * name + * strapline + * earnerDescription + * consumerDescription + * issuerUrl + * rubricUrl + * timeValue + * timeUnits + * limit + * unique + * created + * imageUrl + * type + * archived + * system `[ ]` + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * criteriaUrl + * criteria `[ ]` + * id + * description + * required + * note + * categories `[ ]` + * tags `[ ]` + * milestones `[ ]` + ### Potential errors * **Invalid data** From ddada8b5fb39f2a666ac24b9778a7fb27f84b282 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 21:27:59 +0100 Subject: [PATCH 20/61] Update programs.md --- docs/programs.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/programs.md b/docs/programs.md index 5c0214c..c437f6e 100644 --- a/docs/programs.md +++ b/docs/programs.md @@ -238,14 +238,14 @@ PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. -| Parameters | Required | Description | -|:-----------------------|-----------------|-------------------------| -| **slug** | required | Short, computer-friendly name for the program. Good slugs are lowercase and use dashes instead of spaces, e.g. `cpl-rahms-readers`. Maximum of 50 characters and each program must have a unique slug. -| **name** | required | Name of the program. Maximum of 255 characters. -| **url** | required | URL for the program. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. -| **description** | optional | A short, human-friendly description of the program. Maximum of 255 characters -| **email** | optional | Email address associated with the badge administrator of the program. -| **image** | optional | Image for the program. Should be either multipart data or a URL. +| Parameters | Description | +|:-----------------------|--------------------------| +| **slug** | Short, computer-friendly name for the program. Good slugs are lowercase and use dashes instead of spaces, e.g. `cpl-rahms-readers`. Maximum of 50 characters and each program must have a unique slug. +| **name** | Name of the program. Maximum of 255 characters. +| **url** | URL for the program. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. +| **description** | A short, human-friendly description of the program. Maximum of 255 characters +| **email** | Email address associated with the badge administrator of the program. +| **image** | Image for the program. Should be either multipart data or a URL. You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. From 557ab38895de88330ae2f0ae1075bfe03f9de60f Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 21:57:02 +0100 Subject: [PATCH 21/61] Update badges.md --- docs/badges.md | 322 ++++++++++++++++++++++++++++--------------------- 1 file changed, 184 insertions(+), 138 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index 76ad0b7..b863df3 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -4,28 +4,28 @@ 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_ | -| `name` | string | -| `strapline` | string - _Short tagline description._ | -| `earnerDescription` | string - _Description for potential earners._ | -| `consumerDescription` | string - _Description for viewers of badge e.g. college admin or employer._ | -| `issuerUrl` | string | -| `rubricUrl` | string - _Link to supporting material._ | -| `timeValue` | integer | -| `timeUnits` | _Can be `minutes`, `hours`, `days` or `weeks`._ | -| `limit` | integer - _Optional limit for number of times badge can be earned._ | -| `unique` | boolean | -| `created` | timestamp | -| `imageUrl` | string | -| `type` | string - _Can be automatically assigned in BadgeKit Web app._ | -| `archived` | boolean | -| `system` | _System is represented by ID in database - system details are returned from API endpoints as nested JSON._ | -| `criteriaUrl` | string | -| `criteria` | array - _Includes `id`, `description`, `required` status and `note`._ | -| `categories` | array | -| `tags` | array | -| `milestones` | array | +| `id` | __integer__ - _ID from database entry_ | +| `slug` | __string__ - _Used to identify badge in API endpoints_ | +| `name` | __string__ | +| `strapline` | __string__ - _Short tagline description._ | +| `earnerDescription` | __string__ - _Description for potential earners._ | +| `consumerDescription` | __string__ - _Description for viewers of badge e.g. college admin or employer._ | +| `issuerUrl` | __string__ | +| `rubricUrl` | __string__ - _Link to supporting material._ | +| `timeValue` | __integer__ | +| `timeUnits` | __enum__ - _Can be `minutes`, `hours`, `days` or `weeks`._ | +| `limit` | __integer__ - _Optional limit for number of times badge can be earned._ | +| `unique` | __boolean__ | +| `created` | __timestamp__ | +| `imageUrl` | __string__ | +| `type` | __string__ | +| `archived` | __boolean__ | +| `system` | __integer__ - _System is represented by ID in database - system details are returned from API endpoints as nested JSON._ | +| `criteriaUrl` | __string__ | +| `criteria` | __array__ - _Includes `id`, `description`, `required` status and `note`._ | +| `categories` | __array__ - _Each category is a string._ | +| `tags` | __array__- _Each tag is a string._ | +| [`milestones`](milestones.md) | __array__ - _A milestone badge is awarded when a set of other badges are earned._ | ## Endpoints @@ -298,27 +298,26 @@ 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. -| **strapline** | optional | Short tagline style description of the badge. Maximum 140 characters. -| **earnerDescription** | required | Description of the badge for potential earners. -| **consumerDescription** | required | Description of the badge for consumers viewing it. -| **type** | required | Short string representing badge type. Maximum 255 characters. -| **issuerUrl** | optional | URL for badge issuer. -| **rubricUrl** | optional | Link to any rubric material associated with the badge. -| **timeValue** | optional | Badges can be associated with a time limit for earning. -| **timeUnits** | optional | Time values can be expressed as `minutes`, `hours`, `days` or `weeks`. -| **earnerDescription** | required | Description of the badge for potential earners. -| **limit** | optional | Badges can be awarded to a fixed maximum number of earners. -| **unique** | optional | _boolean_ Badges can be unique. -| **image** OR **imageUrl** | required | Image for the program. Should be either multipart data or a URL. -| **archived** | optional | Boolean indicating archived status for badge. -| **criteriaUrl** | optional | Link to badge criteria. -| **criteria** | optional | Array of criteria items - each criteria should include `description` and `required` status plus optional `note` for badge reviewers. -| **categories** | optional | Array of category names for the badge. -| **tags** | optional | Array of tag names for the badge. -| **milestones** | optional | Array of [milestones](milestones.md). +|:-----------------------|-----------------|--------------------------| +| **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. +| **strapline** | _optional_ | Short tagline style description of the badge. Maximum 140 characters. +| **earnerDescription** | _required_ | Description of the badge for potential earners. +| **consumerDescription** | _required_ | Description of the badge for consumers viewing it. +| **issuerUrl** | _optional_ | URL for badge issuer. +| **rubricUrl** | _optional_ | Link to any rubric material associated with the badge. +| **timeValue** | _optional_ | Badges can be associated with a time limit for earning. +| **timeUnits** | _optional_ | Time values can be expressed as `minutes`, `hours`, `days` or `weeks`. +| **limit** | _optional_ | Badges can be awarded to a fixed maximum number of earners. +| **unique** | _required_ | Boolean indicator of badge uniqueness. +| **image** OR **imageUrl** | _required_ | Image for the program. Should be either multipart data or a URL. +| **archived** | _optional_ | Boolean indicating archived status for badge. +| **criteriaUrl** | _required_ | Link to badge criteria. +| **criteria** | _optional_ | Array of criteria items - each criteria should include `description` and `required` status plus optional `note` for badge reviewers. +| **type** | _required_ | Short string representing badge type. Maximum 255 characters. +| **categories** | _optional_ | Array of category names for the badge. +| **tags** | _optional_ | Array of tag names for the badge. +| **milestones** | _optional_ | Array of [milestones](milestones.md). ### Expected response @@ -415,10 +414,12 @@ Content-Type: application/json * **Invalid data** - ``` + ``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -431,35 +432,37 @@ 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", + "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", "limit": 5, "unique": false, - "imageUrl": "http://example.org/badge.png", + "imageUrl": "http://issuersite.com/badge.png", "archived": false } } - ``` +``` ## Update a Badge @@ -467,8 +470,6 @@ Updates an existing badge. ### Expected request -`PUT /badges/` - Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. ``` @@ -477,99 +478,131 @@ PUT /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug HTTP/1.1 PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug ``` - -``` -Content-Type: application/json - -{ - "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", - "limit": 5, - "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false -} -``` - -``` -Content-Type: application/x-www-form-urlencoded - -name=New%20Badge%20Name&new-slug=badge-slug&strapline=New%20Badge%20Strapline&description=New%20Badge%20Description&image=http%3A%2F%2Fexample.org%2Fnew-image.png -``` - -``` -Content-Type: multipart/form-data; boundary=… - ---… -content-disposition: form-data; name="name" - -New Badge Name ---… -content-disposition: form-data; name="slug" - -new-badge-slug ---… -content-disposition: form-data; name="strapline" - -New Badge Strapline ---… -content-disposition: form-data; name="description" - -New Badge Description ---… -content-disposition: form-data; name="image" - -http://example.org/new-image.png ---…-- -``` - -#### Alternatively… - -Images may be uploaded in the same manner as creating a new 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. +| **strapline** | Short tagline style description of the badge. Maximum 140 characters. +| **earnerDescription** | Description of the badge for potential earners. +| **consumerDescription** | Description of the badge for consumers viewing it. +| **issuerUrl** | URL for badge issuer. +| **rubricUrl** | Link to any rubric material associated with the badge. +| **timeValue** | Badges can be associated with a time limit for earning. +| **timeUnits** | Time values can be expressed as `minutes`, `hours`, `days` or `weeks`. +| **limit** | Badges can be awarded to a fixed maximum number of earners. +| **unique** | Boolean indicator of badge uniqueness. +| **image** OR **imageUrl** | Image for the program. Should be either multipart data or a URL. +| **archived** | Boolean indicating archived status for badge. +| **criteriaUrl** | Link to badge criteria. +| **criteria** | Array of criteria items - each criteria should include `description` and `required` status plus optional `note` for badge reviewers. +| **type** | Short string representing badge type. Maximum 255 characters. +| **categories** | Array of category names for the badge. +| **tags** | Array of tag names for the badge. +| **milestones** | Array of [milestones](milestones.md). + +You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. ### Expected response ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "updated", "badge": { - "name": "Badge Name", + "id": 1, "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", + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Badge description for potential earners.", + "consumerDescription": "Badge description for consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", "timeValue": 10, "timeUnits": "minutes", "limit": 5, "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badge.png", + "type": "badge type", + "archived": false, + "system": { + "id": 1, + "slug": "system-slug", + "url": "http://systemsite.com", + "name": "System Name", + "email": "admin@systemsite.com", + "imageUrl": "http://systemsite.com/image.jpg", + "issuers": [ ] + }, + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ + { + "id": 1, + "description": "criteria description", + "required": 1, + "note": "note for assessor" + }, + ... + ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] } } ``` +#### Response structure + +* status +* badge + * id + * slug + * name + * strapline + * earnerDescription + * consumerDescription + * issuerUrl + * rubricUrl + * timeValue + * timeUnits + * limit + * unique + * created + * imageUrl + * type + * archived + * system `[ ]` + * id + * slug + * url + * name + * email + * imageUrl + * issuers `[ ]` + * criteriaUrl + * criteria `[ ]` + * id + * description + * required + * note + * categories `[ ]` + * tags `[ ]` + * milestones `[ ]` + ### Potential errors * **Invalid data** - ``` +``` HTTP/1.1 400 Bad Request Content-Type: application/json +``` +```json { "code": "ValidationError", "message": "Could not validate required fields", @@ -582,14 +615,16 @@ 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", @@ -610,7 +645,7 @@ Content-Type: application/json "archived": false } } - ``` +``` ## Delete a Badge @@ -629,24 +664,33 @@ DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:ba ``` HTTP/1.1 200 OK Content-Type: application/json +``` +```json { "status": "deleted", "badge": { - "name": "Badge Name", + "id": 1, "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", + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Badge description for potential earners.", + "consumerDescription": "Badge description for consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", "timeValue": 10, "timeUnits": "minutes", "limit": 5, "unique": false, - "imageUrl": "http://example.org/badge.png", - "archived": false + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badge.png", + "type": "badge type", + "archived": false, + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] } } ``` @@ -655,12 +699,14 @@ Content-Type: application/json * **Badge not found** - ``` +``` HTTP/1.1 404 Not Found Content-Type: application/json +``` +```json { "code": "ResourceNotFound", - "message": "Could not find badge with slug ``" + "message": "Could not find badge field: `slug`, value: ``" } - ``` +``` From c1edf7c0a25459a5dacdaa4ca31403de035118e9 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 21:59:04 +0100 Subject: [PATCH 22/61] Create milestones.md --- docs/milestones.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/milestones.md diff --git a/docs/milestones.md b/docs/milestones.md new file mode 100644 index 0000000..a8fb8c8 --- /dev/null +++ b/docs/milestones.md @@ -0,0 +1,7 @@ +# Milestones + +* GET /systems/:slug/milestones +* POST /systems/:slug/milestones +* GET /systems/:slug/milestones/:milestoneId +* PUT /systems/:slug/milestones/:milestoneId +* DELETE /systems/:slug/milestones/:milestoneId From 7dd7adf35bc6e2a16a91ca5359c2113b7fbb95d6 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 21:59:56 +0100 Subject: [PATCH 23/61] Update api-endpoints.md --- docs/api-endpoints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index 988ee4f..da20287 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -116,7 +116,7 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug * Images * **GET** /public/images/:imageId - * Milestones + * [Milestones](milestones.md) * **GET** /systems/:slug/milestones * **POST** /systems/:slug/milestones * **GET** /systems/:slug/milestones/:milestoneId From 4d1a6fd7b18260fbd3cb3bf1b2635a960e0c73a4 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 22:00:56 +0100 Subject: [PATCH 24/61] Update README.md --- docs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.md b/docs/README.md index 3b61fa9..19543f1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ The BadgeKit API docs include the information you need to get started using the * [Programs](programs.md) * Badge Management: * [Badges](badges.md) + * [Milestones](milestones.md) * [Claim Codes](claim-codes.md) * [Issuing](issuing.md) * [Assessment](assessment.md) From 2972f5a7af41969d6e412a80bc35666cf208ff9b Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 23:38:13 +0100 Subject: [PATCH 25/61] Update badges.md --- docs/badges.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/badges.md b/docs/badges.md index b863df3..c728c29 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -656,7 +656,7 @@ Deletes an existing badge. ``` DELETE /systems/:systemSlug/badges/:badgeSlug HTTP/1.1 DELETE /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug HTTP/1.1 -DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug +DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug HTTP/1.1 ``` ### Expected response From 5c2813a21c80ffbac4ef66d61d25d9e40004f8c8 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Wed, 28 May 2014 23:55:06 +0100 Subject: [PATCH 26/61] Update badges.md --- docs/badges.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index c728c29..55a8295 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -294,7 +294,7 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` ``` POST /systems/:systemSlug/badges HTTP/1.1 POST /systems/:systemSlug/issuers/:issuerSlug/badges HTTP/1.1 -POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges +POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/1.1 ``` | Parameters | Required | Description | @@ -475,7 +475,7 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` ``` PUT /systems/:systemSlug/badges/:badgeSlug HTTP/1.1 PUT /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug HTTP/1.1 -PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug +PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug HTTP/1.1 ``` | Parameters | Description | From 949fe8860eed39229c66a86505d2e83ab3da2079 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 00:12:06 +0100 Subject: [PATCH 27/61] Update claim-codes.md First pass through claim codes. --- docs/claim-codes.md | 471 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 450 insertions(+), 21 deletions(-) diff --git a/docs/claim-codes.md b/docs/claim-codes.md index 9360ed1..7b11792 100644 --- a/docs/claim-codes.md +++ b/docs/claim-codes.md @@ -1,23 +1,452 @@ # Claim Codes -* **GET** /systems/:slug/codes/:code -* **GET** /systems/:slug/issuers/:slug/codes/:code -* **GET** /systems/:slug/issuers/:slug/programs/:slug/codes/:code -* **GET** /systems/:slug/badges/:slug/codes -* **GET** /systems/:slug/issuers/:slug/badges/:slug/codes -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes -* **POST** /systems/:slug/badges/:slug/codes -* **POST** /systems/:slug/issuers/:slug/badges/:slug/codes -* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes -* **POST** /systems/:slug/badges/:slug/codes/random -* **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/random -* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/random -* **GET** /systems/:slug/badges/:slug/codes/:code -* **GET** /systems/:slug/issuers/:slug/badges/:slug/codes/:code -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code -* **DELETE** /systems/:slug/badges/:slug/codes/:code -* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/codes/:code -* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code -* **POST** /systems/:slug/badges/:slug/codes/:code/claim -* **POST** /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim -* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim +Earners can use claim codes to claim badges. For example, a claim code can be distributed at an event or given to the earner on completion of an achievement. The issuer site can facilitate issuing badges by allowing earners to submit claim codes. + +| NAME | VALUE | +|:---|:---| +| `id` | __integer__ - _id from database entry_ | +| `code` | __string__ - _code used to claim a badge_ | +| `claimed` | __boolean__ | +| `email` | __string__ | +| `multiuse` | __boolean__ - _claim codes can be single use or multi-use_ | +| `badge` | [badge](badges.md) _claim code is for_ | + +## Endpoints + +* [Retrieve Claim Codes](#retrieve-claim-codes) + * `GET /systems/:slug/badges/:slug/codes` + * `GET /systems/:slug/issuers/:slug/badges/:slug/codes` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes` +* [Retrieve Specific Claim Code](#retrieve-specific-claim-code) + * `GET /systems/:slug/badges/:slug/codes/:code` + * `GET /systems/:slug/issuers/:slug/badges/:slug/codes/:code` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code` +* [Retrieve Badge from Claim Code](#retrieve-badge-from-claim-code) + * `GET /systems/:slug/codes/:code` + * `GET /systems/:slug/issuers/:slug/codes/:code` + * `GET /systems/:slug/issuers/:slug/programs/:slug/codes/:code` +* [Create Claim Code](#create-claim-code) + * `POST /systems/:slug/badges/:slug/codes` + * `POST /systems/:slug/issuers/:slug/badges/:slug/codes` + * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes` +* [Create Random Code](#create-random-code) + * `POST /systems/:slug/badges/:slug/codes/random` + * `POST /systems/:slug/issuers/:slug/badges/:slug/codes/random` + * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/random` +* [Delete Claim Code](#delete-claim-code) + * `DELETE /systems/:slug/badges/:slug/codes/:code` + * `DELETE /systems/:slug/issuers/:slug/badges/:slug/codes/:code` + * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code` +* [Claim a Code](#claim-a-code) + * `POST /systems/:slug/badges/:slug/codes/:code/claim` + * `POST /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim` + * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim` + +## Retrieve Claim Codes + +Retrieves all claim codes for a badge within a system, issuer or program/. + +### Expected request + +``` +GET /systems/:slug/badges/:slug/codes +GET /systems/:slug/issuers/:slug/badges/:slug/codes +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "claimCodes": [ + { + "id": 1, + "code": "0fba9c4457", + "claimed": false, + "email": "someone@somewhere.com", + "multiuse": false + }, + ... + ], + "badge": { + ... + } +} +``` + +#### Response structure + +* claimCodes `[ ]` + * id + * code + * claimed + * email + * multiuse +* [badge](badges.md) + +### Potential errors + +*None* + +## Retrieve Specific Claim Code + +Retrieve the details for a specific claim code for a badge. + +### Expected request + +``` +GET /systems/:slug/badges/:slug/codes/:code +GET /systems/:slug/issuers/:slug/badges/:slug/codes/:code +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "badge": { + ... + }, + "claimCode": { + "id": 1, + "code": "2f91d622dd", + "claimed": false, + "email": null, + "multiuse": false + } +} +``` + +#### Response structure + +* [badge](badges.md) +* claimCode + * id + * code + * claimed + * email + * multiuse + +### Potential errors + +* **Claim code not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find the request claim code: ``" +} +``` + +## Retrieve Badge from Claim Code + +Retrieve the details for a badge using a claim code within a system, issuer or program context. + +### Expected request + +``` +GET /systems/:slug/codes/:code +GET /systems/:slug/issuers/:slug/codes/:code +GET /systems/:slug/issuers/:slug/programs/:slug/codes/:code +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "badge": { + id": 1, + "slug": "badge-slug", + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Description for earners.", + "consumerDescription": "Description for consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badeg.jpg", + "type": "badge type", + "archived": false, + "system": { + ... + }, + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ], + "claimed": 0 + } +} +``` + +#### Response structure + +* [badge](badges.md) + * ... + * claimed + +### Potential errors + +* **Claim code not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find the request claim code: ``" +} +``` + +## Create Claim Code + +Create a claim code for a badge. + +``` +POST /systems/:slug/badges/:slug/codes +POST /systems/:slug/issuers/:slug/badges/:slug/codes +POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes +``` + +## Create Random Code + +Creates a random claim code - BadgeKit API will generate the claim code using a random algorithm. + +### Expected request + +``` +POST /systems/:slug/badges/:slug/codes/random +POST /systems/:slug/issuers/:slug/badges/:slug/codes/random +POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/random +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | Description | +|:-----------------------|-----------------|--------------------------| +| **claimed** | optional | Boolean indicator of whether the badge has been claimed. +| **multiuse** | optional | Boolean indicator of whether the badge is multiuse or not (single use). +| **email** | optional | + +### Expected response + +``` +HTTP/1.1 201 Created +Content-Type: application/json +``` + +```json +{ + "status": "created", + "claimCode": { + "id": 1, + "code": "0fba9c4457", + "claimed": false, + "multiuse": false + }, + "badge": { + ... + } +} +``` + +#### Response structure + +* status +* claimCode + * id + * code + * claimed + * multiuse +* [badge](badges.md) + +### Potential errors + +*None* + +## Delete Claim Code + +Delete a claim code. + +### Expected request + +``` +DELETE /systems/:systemSlug/badges/:badgeSlug/codes/:code +DELETE /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug +DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug/codes/:code +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "deleted", + "claimCode": { + "id": 1, + "code": "0fba9c4457", + "claimed": false, + "email": null, + "multiuse": false + }, + "badge": { + "id": 1, + "slug": "badge-slug", + "name": "Badge Name", + "strapline": "Badge strapline.", + "earnerDescription": "Badge description for potential earners.", + "consumerDescription": "Badge description for consumers.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 10, + "timeUnits": "minutes", + "limit": 5, + "unique": false, + "created": "2014-05-21T19:22:09.000Z", + "imageUrl": "http://issuersite.com/badge.png", + "type": "badge type", + "archived": false, + "criteriaUrl": "http://issuersite.com/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] + } +} +``` + +#### Response structure + +* status +* claimCode +* [badge](badges.md) + +### Potential errors + +* **Claim code not found** + +``` + HTTP/1.1 404 Not Found + Content-Type: application/json +``` + +```json + { + "code": "ResourceNotFound", + "message": "Could not find claimCode field: `code`, value: ``" + } +``` + +## Claim a Code + +Claim a code. + +### Expected request + +``` +POST /systems/:slug/badges/:slug/codes/:code/claim +POST /systems/:slug/issuers/:slug/badges/:slug/codes/:code/claim +POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes/:code/claim +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | +|:-----------------------|-----------------| +| **email** | optional | + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "updated", + "claimCode": { + "id": 1, + "code": "abcde12345", + "claimed": false, + "email": null, + "multiuse": false + }, + "badge": { + ... + } +} +``` + +#### Response structure + +* status +* claimCode + * id + * code + * claimed + * email + * multiuse +* [badge](badges.md) + +### Potential errors + +* **Claim code already claimed (if single use)** + +``` +HTTP/1.1 400 Bad Request +Content-Type: application/json +``` + +```json +{ + "code": "CodeAlreadyUsed", + "message": "Claim code `code` has already been claimed" +} +``` + +* **Claim code not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find claimCode field: `code`, value: ``" +} +``` From 2df0ac3e93276723497f7e35bdf4c08cf8cdf4c2 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 00:13:43 +0100 Subject: [PATCH 28/61] Update claim-codes.md --- docs/claim-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/claim-codes.md b/docs/claim-codes.md index 7b11792..be9844b 100644 --- a/docs/claim-codes.md +++ b/docs/claim-codes.md @@ -175,7 +175,7 @@ Content-Type: application/json ```json { "badge": { - id": 1, + "id": 1, "slug": "badge-slug", "name": "Badge Name", "strapline": "Badge strapline.", From 8db20c58c5292de67f24a7acb19a67b2aa42869c Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 11:32:26 +0100 Subject: [PATCH 29/61] Update claim-codes.md --- docs/claim-codes.md | 86 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/docs/claim-codes.md b/docs/claim-codes.md index be9844b..bc06e03 100644 --- a/docs/claim-codes.md +++ b/docs/claim-codes.md @@ -230,12 +230,96 @@ Content-Type: application/json Create a claim code for a badge. +### Expected request + ``` POST /systems/:slug/badges/:slug/codes POST /systems/:slug/issuers/:slug/badges/:slug/codes POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/codes ``` +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | Description | +|:-----------------------|-----------------|--------------------------| +| **code** | required | The claim code you are creating. String with maximum length 255 characters. | +| **claimed** | optional | Boolean indicator of whether the badge has been claimed. +| **multiuse** | optional | Boolean indicator of whether the badge is multiuse or not (single use). +| **email** | optional | + +### Expected response + +``` +HTTP/1.1 201 Created +Content-Type: application/json +``` + +```json +{ + "status": "created", + "claimCode": { + "id": 1, + "code": "abcde12345", + "claimed": false, + "multiuse": false + }, + "badge": { + ... + } +} +``` + +#### Response structure + +* status +* claimCode + * id + * code + * claimed + * multiuse +* [badge](badges.md) + +#### Potential errors + +* **Invalid data** + +``` + HTTP/1.1 400 Bad Request + Content-Type: application/json +``` + +```json + { + "code": "ValidationError", + "message": "Could not validate required fields", + "details": [ + { + "message": "String is not in range", + "field": "code", + "value": "..." + }, + ... + ] + } +``` + +* **Duplicate entry** + +``` + HTTP/1.1 409 Conflict + Content-Type: application/json +``` + +```json + { + "code": "ResourceConflict", + "error": "claimCode with that `code` already exists", + "details": { + ... + } + } +``` + ## Create Random Code Creates a random claim code - BadgeKit API will generate the claim code using a random algorithm. @@ -268,7 +352,7 @@ Content-Type: application/json "status": "created", "claimCode": { "id": 1, - "code": "0fba9c4457", + "code": "abcde12345", "claimed": false, "multiuse": false }, From 64945525ed59317513f5c516e8893a16cb632144 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 11:42:39 +0100 Subject: [PATCH 30/61] Update issuing.md --- docs/issuing.md | 92 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 76 insertions(+), 16 deletions(-) diff --git a/docs/issuing.md b/docs/issuing.md index f332a12..53a3d13 100644 --- a/docs/issuing.md +++ b/docs/issuing.md @@ -1,18 +1,78 @@ # Issuing -* **GET** /systems/:slug/instances/:email -* **GET** /systems/:slug/issuers/:slug/instances/:email -* **GET** /systems/:slug/issuers/:slug/programs/:slug/instances/:email -* **GET** /systems/:slug/badges/:slug/instances -* **GET** /systems/:slug/issuers/:slug/badges/:slug/instances -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances -* **GET** /systems/:slug/badges/:slug/instances/:email -* **GET** /systems/:slug/issuers/:slug/badges/:slug/instances/:email -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email -* **POST** /systems/:slug/badges/:slug/instances -* **POST** /systems/:slug/issuers/:slug/badges/:slug/instances -* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances -* **DELETE** /systems/:slug/badges/:slug/instances/:email -* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email -* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email -* **GET** /public/assertions/:slug +Issuing is the process of awarding a badge to a specific earner. In BadgeKit API, issuing a badge means creating a badge instance. __Note that when a review is submitted in which an earner application for a badge is approved, this does not mean that the badge is automatically issued. Issuer sites must use the below API endpoints to issue badges, marking any relevant applications as processed when this occurs. These endpoints also apply to badges issued without the assessment process, for example badges issued directly to earner email addresses or using claim codes.__ + +## Endpoints + +* [Retrieve Badge Instances](#retrieve-badge-instances) + * `GET /systems/:slug/badges/:slug/instances` + * `GET /systems/:slug/issuers/:slug/badges/:slug/instances` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances` +* [Retrieve a Specific Instance](#retrieve-a-specific-instance) + * `GET /systems/:slug/instances/:email` + * `GET /systems/:slug/issuers/:slug/instances/:email` + * `GET /systems/:slug/issuers/:slug/programs/:slug/instances/:email` + * `GET /systems/:slug/badges/:slug/instances/:email` + * `GET /systems/:slug/issuers/:slug/badges/:slug/instances/:email` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email` +* [Create a Badge Instance](#create-a-badge-instance) + * `POST /systems/:slug/badges/:slug/instances` + * `POST /systems/:slug/issuers/:slug/badges/:slug/instances` + * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances` +* [Delete an Instance](#delete-an-instance) + * `DELETE /systems/:slug/badges/:slug/instances/:email` + * `DELETE /systems/:slug/issuers/:slug/badges/:slug/instances/:email` + * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email` + +## Retrieve Badge Instances + +Retrieves all instances for a specific badge within a [system](systems.md), [issuer](issuers.md) or [program](programs.md). + +### Expected request + +``` +GET /systems/:slug/badges/:slug/instances +GET /systems/:slug/issuers/:slug/badges/:slug/instances +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json + +``` + +## Retrieve a Specific Instance + +## Create a Badge Instance + +To actually issue (or "award") a badge to an earner in BadgeKit API, you create a badge instance. A badge instance is an awarded badge, issued to a specific earner. + +### Expected request + +``` +POST /systems/:slug/badges/:slug/instances +POST /systems/:slug/issuers/:slug/badges/:slug/instances +POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | Description | +|:-----------------------|-----------------|--------------------------| +| **email** | required | The email address for the earner the badge is being issued to. | +| **claimCode** | optional | A claim code for the badge. | +| **slug** | optional | Instance slug. | +| **issuedOn** | optional | Date issued. | +| **expires** | optional | Date instance expires. | + + + +## Delete an Instance + + From f0c06d17b62123626e9b6aba03d06450ee555aba Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 18:06:31 +0100 Subject: [PATCH 31/61] Update issuing.md --- docs/issuing.md | 252 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 249 insertions(+), 3 deletions(-) diff --git a/docs/issuing.md b/docs/issuing.md index 53a3d13..0c0d5e2 100644 --- a/docs/issuing.md +++ b/docs/issuing.md @@ -2,6 +2,18 @@ Issuing is the process of awarding a badge to a specific earner. In BadgeKit API, issuing a badge means creating a badge instance. __Note that when a review is submitted in which an earner application for a badge is approved, this does not mean that the badge is automatically issued. Issuer sites must use the below API endpoints to issue badges, marking any relevant applications as processed when this occurs. These endpoints also apply to badges issued without the assessment process, for example badges issued directly to earner email addresses or using claim codes.__ +## Badge Instances + +| NAME | VALUE | +|:---|:---| +| `slug` | __string__ | +| `email` | __email address__ - _earner email_ | +| `expires` | __timestamp__ - _optional expiry date_ | +| `issuedOn` | __timestamp__ - _API will generate_ | +| `claimCode` | [claim code](claim-codes.md) - _if badge is issued using claim code_ | +| `assertionUrl` | __url__ - _location of issued badge assertion, generated by API_ | +| `badge` | [badge](badges.md) - _API endpoints return badge issued along with instances_ | + ## Endpoints * [Retrieve Badge Instances](#retrieve-badge-instances) @@ -44,11 +56,113 @@ Content-Type: application/json ``` ```json - +{ + "instances": [ + { + "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", + "badge": { + "id": 1, + "slug": "badge-slug", + ... + } + }, + ... + ] +} ``` +#### Response structure + +* instances `[ ]` + * slug + * email + * expires + * issuedOn + * claimCode + * assertionUrl + * [badge](badges.md) + +### Potential errors + +*None* + ## Retrieve a Specific Instance +Retrieve a specific instance of a badge. + +### Expected request + +``` +GET /systems/:slug/instances/:email +GET /systems/:slug/issuers/:slug/instances/:email +GET /systems/:slug/issuers/:slug/programs/:slug/instances/:email +GET /systems/:slug/badges/:slug/instances/:email +GET /systems/:slug/issuers/:slug/badges/:slug/instances/:email +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email +``` + +You can retrieve instances of badges awarded to a particular email address, for systems, issuers, programs and badges. + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "instances": [ + { + "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", + "badge": { + "id": 1, + "slug": "badge-slug", + ... + } + }, + ... + ] +} +``` + +#### Response structure + +* instances `[ ]` + * slug + * email + * expires + * issuedOn + * claimCode + * assertionUrl + * [badge](badges.md) + +### Potential errors + +* **Instance not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find badgeInstance field: `email`, value: " +} +``` + ## Create a Badge Instance To actually issue (or "award") a badge to an earner in BadgeKit API, you create a badge instance. A badge instance is an awarded badge, issued to a specific earner. @@ -71,8 +185,140 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` | **issuedOn** | optional | Date issued. | | **expires** | optional | Date instance expires. | - +### Expected response + +``` +HTTP/1.1 201 Created +Content-Type: application/json +``` + +```json +{ + "status": "created", + "instance": { + "slug": "abcdefghi123456789abcdefghi123456789", + "email": "earner@somedomain.com", + "expires": null, + "issuedOn": "2014-05-29T10:16:01.654Z", + "claimCode": "abcde12345", + "assertionUrl": "http://issuersite.com/public/assertions/abcdefghi123456789abcdefghi123456789", + "badge": null + } +} +``` + +The assertion URL represents the location of the badge assertion. A badge assertion contains the details of an issued badge. See the latest [assertion](https://github.com/mozilla/openbadges-specification/blob/master/Assertion/latest.md) specification for more information. Claim code is only returned if the badge instance was created using a claim code. + +#### Response structure + +* status +* instance + * slug + * email + * expires + * issuedOn + * claimCode + * assertionUrl + * [badge](badges.md) + +#### 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": "email", + "value": "..." + }, + ... + ] + } +``` + +* **Duplicate entry** + +``` + HTTP/1.1 409 Conflict + Content-Type: application/json +``` + +```json + { + "code": "ResourceConflict", + "message": "User has already been awarded badge ", + "details": { + "assertionUrl": "http://issuersite.com/public/assertions/abcde..." + ... + } + } +``` ## Delete an Instance - +Delete a badge instance within a system, issuer or program context. + +### Expected request + +``` +DELETE /systems/:slug/badges/:slug/instances/:email +DELETE /systems/:slug/issuers/:slug/badges/:slug/instances/:email +DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "instance": { + "slug": "abcdefghi123456789abcdefghi123456789", + "email": "earner@somedomain.com", + "expires": null, + "issuedOn": "2014-05-29T10:16:01.654Z", + "claimCode": "abcde12345", + "assertionUrl": "http://issuersite.com/public/assertions/abcdefghi123456789abcdefghi123456789", + "badge": { + ... + } + } +} +``` + +#### Response structure + +* instance + * slug + * email + * expires + * issuedOn + * claimCode + * assertionUrl + * [badge](badges.md) + +#### Potential errors + +* **Instance not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find badgeInstance field: `email`, value: " +} +``` From 1d32fe4965f99f6d701a16ec130afde526e057a4 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 18:13:51 +0100 Subject: [PATCH 32/61] Update issuing.md --- docs/issuing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/issuing.md b/docs/issuing.md index 0c0d5e2..adaede9 100644 --- a/docs/issuing.md +++ b/docs/issuing.md @@ -272,6 +272,7 @@ Delete a badge instance within a system, issuer or program context. DELETE /systems/:slug/badges/:slug/instances/:email DELETE /systems/:slug/issuers/:slug/badges/:slug/instances/:email DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email +``` ### Expected response From 0b16d038034f5352e8ede15a1fdffd6ce20538b7 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 20:52:15 +0100 Subject: [PATCH 33/61] Update issuers.md --- docs/issuers.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/issuers.md b/docs/issuers.md index 7385cb1..5c03d25 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -279,14 +279,14 @@ PUT /systems/:systemSlug/issuers/:issuerSlug Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. -| Parameters | Required | Description | -|:-----------------------|-----------------|-------------------------| -| **slug** | required | Short, computer-friendly name for the issuer. Good slugs are lowercase and use dashes instead of spaces, e.g. `chicago-public-library`. Maximum of 50 characters and each issuer must have a unique slug. -| **name** | required | Name of the issuer. Maximum of 255 characters. -| **url** | required | URL for the issuer. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. -| **description** | optional | A short, human-friendly description of the issuer. Maximum of 255 characters -| **email** | optional | Email address associated with the badge administrator of the issuer. -| **image** | optional | Image for the issuer. Should be either multipart data or a URL. +| Parameters | Description | +|:-----------------------|--------------------------| +| **slug** | Short, computer-friendly name for the issuer. Good slugs are lowercase and use dashes instead of spaces, e.g. `chicago-public-library`. Maximum of 50 characters and each issuer must have a unique slug. +| **name** | Name of the issuer. Maximum of 255 characters. +| **url** | URL for the issuer. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. +| **description** | A short, human-friendly description of the issuer. Maximum of 255 characters +| **email** | Email address associated with the badge administrator of the issuer. +| **image** | Image for the issuer. Should be either multipart data or a URL. You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. From 14cbef9dd6735ce9ae3f201e12c2a2ad5f0601bd Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 20:53:11 +0100 Subject: [PATCH 34/61] Update systems.md --- docs/systems.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/systems.md b/docs/systems.md index bb73f72..4a8c4e9 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -287,14 +287,14 @@ PUT /systems/:systemSlug Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. -| Parameters | Required | Description | -|:-----------------------|-----------------|-------------------------| -| **slug** | required | Short, computer-friendly name for the system. Good slugs are lowercase and use dashes instead of spaces, e.g. `city-of-chicago`. Maximum of 50 characters and each system must have a unique slug. -| **name** | required | Name of the system. Maximum of 255 characters. -| **url** | required | URL for the system. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. -| **description** | optional | A short, human-friendly description of the system. Maximum of 255 characters -| **email** | optional | Email address associated with the badge administrator of the system. -| **image** | optional | Image for the system. Should be either multipart data or a URL. +| Parameters | Description | +|:-----------------------|--------------------------| +| **slug** | Short, computer-friendly name for the system. Good slugs are lowercase and use dashes instead of spaces, e.g. `city-of-chicago`. Maximum of 50 characters and each system must have a unique slug. +| **name** | Name of the system. Maximum of 255 characters. +| **url** | URL for the system. Must be fully qualified, e.g. https://www.example.org, **NOT** just www.example.org. +| **description** | A short, human-friendly description of the system. Maximum of 255 characters +| **email** | Email address associated with the badge administrator of the system. +| **image** | Image for the system. Should be either multipart data or a URL. You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. From 40be9cb513e2042fa25059355f5d67edfb27344c Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 21:04:19 +0100 Subject: [PATCH 35/61] Update assessment.md --- docs/assessment.md | 888 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 855 insertions(+), 33 deletions(-) diff --git a/docs/assessment.md b/docs/assessment.md index a0ce3d8..b4fd457 100644 --- a/docs/assessment.md +++ b/docs/assessment.md @@ -1,35 +1,857 @@ # Assessment -* **GET** /systems/:slug/applications -* **GET** /systems/:slug/issuers/:slug/applications -* **GET** /systems/:slug/issuers/:slug/programs/:slug/applications -* **GET** /systems/:slug/badges/:slug/applications -* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications -* **POST** /systems/:slug/badges/:slug/applications -* **POST** /systems/:slug/issuers/:slug/badges/:slug/applications -* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications -* **PUT** /systems/:slug/badges/:slug/applications/:slug -* **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug -* **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug -* **GET** /systems/:slug/badges/:slug/applications/:slug -* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug -* **DELETE** /systems/:slug/badges/:slug/applications/:slug -* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug -* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug -* **GET** /systems/:slug/badges/:slug/applications/:slug/reviews -* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews -* **GET** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug -* **GET** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug -* **GET** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug -* **POST** /systems/:slug/badges/:slug/applications/:slug/reviews -* **POST** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews -* **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews -* **PUT** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug -* **PUT** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug -* **PUT** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug -* **DELETE** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug -* **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug -* **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug +Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting reviews. When a review is submitted, issuers can detect this at their [webhook](webhooks.md). Typically an issuer will respond to an approved review by offering the earner the badge, creating a [badge instance](issuing.md) and marking the application as processed using the updating endpoint below. + +## Endpoints + +* [Retrieve Applications](retrieve-applications) + * `GET /systems/:slug/applications` + * `GET /systems/:slug/issuers/:slug/applications` + * `GET /systems/:slug/issuers/:slug/programs/:slug/applications` + * `GET /systems/:slug/badges/:slug/applications` + * `GET /systems/:slug/issuers/:slug/badges/:slug/applications` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications` +* [Retrieve a Specific Application](#retrieve-a-specific-application) + * `GET /systems/:slug/badges/:slug/applications/:slug` + * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug` +* [Submit an Application](#submit-an-application) + * `POST /systems/:slug/badges/:slug/applications` + * `POST /systems/:slug/issuers/:slug/badges/:slug/applications` + * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications` +* [Update an Application](#update-an-application) + * `PUT /systems/:slug/badges/:slug/applications/:slug` + * `PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug` + * `PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug` +* [Delete an Application](#delete-an-application) + * `DELETE /systems/:slug/badges/:slug/applications/:slug` + * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug` + * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug` +* [Retrieve Application Reviews](#retrieve-application-reviews) + * `GET /systems/:slug/badges/:slug/applications/:slug/reviews` + * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews` +* [Retrieve a Specific Review](#retrieve-a-specific-review) + * `GET /systems/:slug/badges/:slug/applications/:slug/reviews/:slug` + * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug` + * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug` +* [Submit an Application Review](#submit-an-application-review) + * `POST /systems/:slug/badges/:slug/applications/:slug/reviews` + * `POST /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews` + * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews` +* [Update a Review](#update-a-review) + * `PUT /systems/:slug/badges/:slug/applications/:slug/reviews/:slug` + * `PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug` + * `PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug` +* [Delete a Review](#delete-a-review) + * `DELETE /systems/:slug/badges/:slug/applications/:slug/reviews/:slug` + * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug` + * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug` + +## Applications + +| NAME | VALUE | +|:---|:---| +| `id` | __integer__ - _id from database_ | +| `slug` | __string__ | +| `learner` | __email address__ - _earner email_ | +| `created` | __timestamp__ | +| `assignedTo` | __string__ _email login for assigned reviewer_ | +| `assignedExpiration` | __timestamp__ | +| `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)_ | + +## Reviews + +| NAME | VALUE | +|:---|:---| +| `id` | __integer__ - _id from database_ | +| `slug` | __string__ | +| `author` | __email address__ - _reviewer email_ | +| `comment` | __string__ - _applicant feedback_ | +| `reviewItems` | __array__ - _one for each criteria item for badge, each reviewItem can include `criterionId` for badge criteria, `satisfied` status and `comment`_ | +| `approved` | __boolean__ - _indicates success of application_ | + +## Retrieve Applications + +Retrieve existing applications within a system, issuer or program or for a specific badge. + +### Expected request + +``` +GET /systems/:slug/applications +GET /systems/:slug/issuers/:slug/applications +GET /systems/:slug/issuers/:slug/programs/:slug/applications +GET /systems/:slug/badges/:slug/applications +GET /systems/:slug/issuers/:slug/badges/:slug/applications +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "applications": [ + { + "id": 1, + "slug": "application-slug", + "learner": "earner@adomain.com", + "created": "2014-05-29T18:24:59.000Z", + "assignedTo": null, + "assignedExpiration": null, + "badge": { + ... + }, + "processed": null, + "evidence": [ + { + "url": null, + "mediaType": null, + "reflection": "I did things relevant to the badge..." + }, + { + "url": "http://issuersite.com/uploaded-image.jpg", + "mediaType": "image", + "reflection": "A picture of my evidence." + }, + { + "url": "http://awebsite.com/evidence.html", + "mediaType": "link", + "reflection": "My website where I did things." + } + ] + }, + ... + ] +} +``` + +#### Response structure + +* applications `[ ]` + * id + * slug + * learner + * created + * assignedTo + * assignedExpiration + * [badge](badges.md) + * processed + * evidence `[ ]` + * url + * mediaType + * reflection + +### Potential errors + +*None* + +## Retrieve a Specific Application + +Retrieve the details for a specific application using its slug. + +### Expected request + +``` +GET /systems/:slug/badges/:slug/applications/:slug +GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "application": + { + "id": 1, + "slug": "application-slug", + "learner": "earner@adomain.com", + "created": "2014-05-29T18:24:59.000Z", + "assignedTo": null, + "assignedExpiration": null, + "badge": { + ... + }, + "processed": null, + "evidence": [ + { + "url": null, + "mediaType": null, + "reflection": "I did things relevant to the badge..." + }, + { + "url": "http://issuersite.com/uploaded-image.jpg", + "mediaType": "image", + "reflection": "A picture of my evidence." + }, + { + "url": "http://awebsite.com/evidence.html", + "mediaType": "link", + "reflection": "My website where I did things." + } + ] + }, + ... + ] +} +``` + +#### Response structure + +* application + * id + * slug + * learner + * created + * assignedTo + * assignedExpiration + * [badge](badges.md) + * processed + * evidence `[ ]` + * url + * mediaType + * reflection + +### Potential errors + +* **Application not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find application field: `slug`, value: ``" +} +``` + +## Submit an Application + +Post an earner application for a badge. _If you're using the BadgeKit Web app, submitted applications appear there for review._ + +### Expected request + +``` +POST /systems/:slug/badges/:slug/applications +POST /systems/:slug/issuers/:slug/badges/:slug/applications +POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | Description | +|:-----------------------|-----------------|--------------------------| +| **learner** | required | The email address for the earner applying. | +| **evidence** | optional | Array including evidence items - each item can include `reflection`, `mediaType` and/or `url`. | +| **assignedTo** | optional | Reviewer application is assigned to. | +| **assignedExpiration** | optional | Expiry date. | + +### Expected response + +``` +HTTP/1.1 201 Created +Content-Type: application/json +``` + +```json +{ + "status": "created", + "application": + { + "id": 1, + "slug": "abcdef123456", + "learner": "earner@example.com", + "created": "2014-05-06T12:24:45.000Z", + "assignedTo": null, + "assignedExpiration": null, + "badge": + { + ... + }, + + "processed": null, + "evidence": + [ + { + "url": "http://awebsite.com/page", + "mediaType": "link", + "reflection": "I did great stuff." + } + ] + } +} +``` + +## Response structure + +* status +* application + * id + * slug + * learner + * created + * assignedTo + * assignedExpiration + * [badge](badges.md) + * processed + * evidence `[ ]` + * url + * mediaType + * reflection + +#### 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": "learner", + "value": "..." + }, + ... + ] + } +``` + +## Update an Application + +Update an existing application - a typical use of this endpoint would be to mark an application as processed, for example following review and badge issuing. + +### Expected request + +``` +PUT /systems/:slug/badges/:slug/applications/:slug +PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug +PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Description | +|:-----------------------|--------------------------| +| **learner** | The email address for the earner applying. | +| **evidence** | Array including evidence items - each item can include `reflection`, `mediaType` and/or `url`. | +| **assignedTo** | Reviewer application is assigned to. | +| **assignedExpiration** | Expiry date. | +| **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. + +### Expected response + + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "updated", + "application": + { + "id": 1, + "slug": "abcdef123456", + "learner": "earner@example.com", + "created": "2014-05-06T12:24:45.000Z", + "assignedTo": null, + "assignedExpiration": null, + "badge": + { + ... + }, + + "processed": "2014-05-06T12:24:45.000Z", + "evidence": + [ + { + "url": "http://awebsite.com/page", + "mediaType": "link", + "reflection": "I did great stuff." + } + ] + } +} +``` + +#### Response structure + +* status +* application + * id + * slug + * learner + * created + * assignedTo + * assignedExpiration + * [badge](badges.md) + * processed + * evidence `[ ]` + * url + * mediaType + * reflection + +### Potential errors + +* **Invalid data** + +``` + HTTP/1.1 400 Bad Request + Content-Type: application/json +``` + +```json + { + "code": "ValidationError", + "message": "Could not validate required fields", + "details": [ + { + "message": "Invalid email", + "field": "learner", + "value": "..." + }, + ... + ] + } +``` + +## Delete an Application + +Delete an existing application. + +### Expected request + +``` +DELETE /systems/:slug/badges/:slug/applications/:slug +DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug +DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "deleted", + "application": { + "id": 1, + "slug": "abcde12345", + "learner": "earner@adomain.com", + "created": "2014-05-29T18:24:59.000Z", + "assignedTo": null, + "assignedExpiration": null, + "badge": null, + "processed": null, + "evidence": [ ] + } + +} +``` + +### Potential errors + +* **Issuer not found** + +``` + HTTP/1.1 404 Not Found + Content-Type: application/json +``` + +```json + { + "code": "ResourceNotFound", + "message": "Could not find application field: `slug`, value: ``" + } +``` + +## Retrieve Application Reviews + +Retrieve reviews for applications. + +### Expected request + +``` +GET /systems/:slug/badges/:slug/applications/:slug/reviews +GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "reviews": [ + { + "id": 1, + "slug": "abcde12345", + "author": "reviewer@issuersite.com", + "comment": "fantastic work", + "reviewItems": [ + { + "criterionId": 1, + "satisfied": 0, + "comment": "perfect" + }, + ... + ] + }, + ... + ] +} +``` + +#### Response structure + +* reviews `[ ]` + * id + * slug + * author + * comment + * reviewItems `[ ]` + * criterionId + * satisfied + * comment + +### Potential errors + +*None* + +## Retrieve a Specific Review + +Retrieve a specific application review for a badge. + +### Expected request + +``` +GET /systems/:slug/badges/:slug/applications/:slug/reviews/:slug +GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug +GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "review": + { + "id": 1, + "slug": "abcde12345", + "author": "reviewer@issuersite.com", + "comment": "fantastic work", + "reviewItems": [ + { + "criterionId": 1, + "satisfied": 0, + "comment": "perfect" + }, + ... + ] + } +} +``` + +#### Response structure + +* reviews + * id + * slug + * author + * comment + * reviewItems `[ ]` + * criterionId + * satisfied + * comment + +### Potential errors + +* **Issuer not found** + +``` + HTTP/1.1 404 Not Found + Content-Type: application/json +``` + +```json + { + "code": "ResourceNotFound", + "message": "Could not find review field: `slug`, value ``" + } +``` + +## Submit an Application Review + +Post a review for an application. + +### Expected request + +``` +POST /systems/:slug/badges/:slug/applications/:slug/reviews +POST /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews +POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | Description | +|:-----------------------|-----------------|--------------------------| +| **author** | required | Email address of reviewer. +| **comment** | optional | Feedback for earner. +| **reviewItems** | optional | Array, each item includes `criterionId`, `satisfied` and `comment`. + +### Expected response + + +``` +HTTP/1.1 201 Created +Content-Type: application/json +``` + +```json +{ + "status": "created", + "review": { + "id": 1, + "slug": "abcde12345", + "author": "reviewer@issuersite.com", + "comment": "fantastic work", + "reviewItems": [ + { + "criterionId": 1, + "satisfied": 0, + "comment": "perfect" + }, + ... + ] + } + +} +``` + +#### Response structure + +* status +* review + * id + * slug + * author + * comment + * reviewItems `[ ]` + * criterionId + * satisfied + * comment + +### Potential errors + +* **Invalid data** + +``` + HTTP/1.1 400 Bad Request + Content-Type: application/json +``` + +```json + { + "code": "ValidationError", + "message": "Could not validate required fields", + "details": [ + { + "message": "Invalid email", + "field": "author", + "value": "..." + }, + ... + ] + } +``` + +## Update a Review + +Update an existing application review for a badge. + +### Expected request + +``` +PUT /systems/:slug/badges/:slug/applications/:slug/reviews/:slug +PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug +PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Description | +|:-----------------------|--------------------------| +| **author** | Email address of reviewer. +| **comment** | Feedback for earner. +| **reviewItems** | Array, each item includes `criterionId`, `satisfied` and `comment`. + +You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "updated", + "review": { + "id": 1, + "slug": "abcde12345", + "author": "someoneelse@issuersite.com", + "comment": "fantastic work", + "reviewItems": [ + { + "criterionId": 1, + "satisfied": 0, + "comment": "perfect" + }, + ... + ] + } +} +``` + +#### Response structure + +* status +* review + * id + * slug + * author + * comment + * reviewItems `[ ]` + * criterionId + * satisfied + * comment + +### Potential errors + +* **Invalid data** + +``` + HTTP/1.1 400 Bad Request + Content-Type: application/json +``` + +```json + { + "code": "ValidationError", + "message": "Could not validate required fields", + "details": [ + { + "message": "Invalid email", + "field": "author", + "value": "..." + }, + ... + ] + } +``` + +## Delete a Review + +Delete an existing application review for a badge. + +### Expected request + +``` +DELETE /systems/:slug/badges/:slug/applications/:slug/reviews/:slug +DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug +DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "status": "deleted", + "badge": { + "id": 1, + "slug": "abcde12345", + "author": "reviewer@issuersite.com", + "comment": "fantastic work", + "reviewItems": [ + { + "criterionId": 1, + "satisfied": 0, + "comment": "perfect" + }, + ... + ] + } +} +``` + +#### Response structure + +* status +* review + * id + * slug + * author + * comment + * reviewItems `[ ]` + * criterionId + * satisfied + * comment + +### Potential errors + +* **Program not found** + +``` + HTTP/1.1 404 Not Found + Content-Type: application/json +``` + +```json + { + "code": "ResourceNotFound", + "message": "Could not find review field: `slug`, value: ``" + } +``` From f6a29eea9a3af9bc03278aee7a2325836482a1f2 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 22:20:45 +0100 Subject: [PATCH 36/61] Update assessment.md --- docs/assessment.md | 52 +++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/assessment.md b/docs/assessment.md index b4fd457..046b012 100644 --- a/docs/assessment.md +++ b/docs/assessment.md @@ -2,9 +2,34 @@ Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting reviews. When a review is submitted, issuers can detect this at their [webhook](webhooks.md). Typically an issuer will respond to an approved review by offering the earner the badge, creating a [badge instance](issuing.md) and marking the application as processed using the updating endpoint below. +## Applications + +| NAME | VALUE | +|:---|:---| +| `id` | __integer__ - _id from database_ | +| `slug` | __string__ | +| `learner` | __email address__ - _earner email_ | +| `created` | __timestamp__ | +| `assignedTo` | __string__ _email login for assigned reviewer_ | +| `assignedExpiration` | __timestamp__ | +| `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)_ | + +## Reviews + +| NAME | VALUE | +|:---|:---| +| `id` | __integer__ - _id from database_ | +| `slug` | __string__ | +| `author` | __email address__ - _reviewer email_ | +| `comment` | __string__ - _applicant feedback_ | +| `reviewItems` | __array__ - _one for each criteria item for badge, each reviewItem can include `criterionId` for badge criteria, `satisfied` status and `comment`_ | +| `approved` | __boolean__ - _indicates success of application_ | + ## Endpoints -* [Retrieve Applications](retrieve-applications) +* [Retrieve Applications](#retrieve-applications) * `GET /systems/:slug/applications` * `GET /systems/:slug/issuers/:slug/applications` * `GET /systems/:slug/issuers/:slug/programs/:slug/applications` @@ -48,31 +73,6 @@ Badges can be issued following assessment of earner applications. Issuers can al * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug` * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug` -## Applications - -| NAME | VALUE | -|:---|:---| -| `id` | __integer__ - _id from database_ | -| `slug` | __string__ | -| `learner` | __email address__ - _earner email_ | -| `created` | __timestamp__ | -| `assignedTo` | __string__ _email login for assigned reviewer_ | -| `assignedExpiration` | __timestamp__ | -| `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)_ | - -## Reviews - -| NAME | VALUE | -|:---|:---| -| `id` | __integer__ - _id from database_ | -| `slug` | __string__ | -| `author` | __email address__ - _reviewer email_ | -| `comment` | __string__ - _applicant feedback_ | -| `reviewItems` | __array__ - _one for each criteria item for badge, each reviewItem can include `criterionId` for badge criteria, `satisfied` status and `comment`_ | -| `approved` | __boolean__ - _indicates success of application_ | - ## Retrieve Applications Retrieve existing applications within a system, issuer or program or for a specific badge. From 9c8f8dfef31b9b4002a4802ff4e241c06914c527 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 23:25:12 +0100 Subject: [PATCH 37/61] Update milestones.md --- docs/milestones.md | 462 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 457 insertions(+), 5 deletions(-) diff --git a/docs/milestones.md b/docs/milestones.md index a8fb8c8..0c3cc06 100644 --- a/docs/milestones.md +++ b/docs/milestones.md @@ -1,7 +1,459 @@ # Milestones -* GET /systems/:slug/milestones -* POST /systems/:slug/milestones -* GET /systems/:slug/milestones/:milestoneId -* PUT /systems/:slug/milestones/:milestoneId -* DELETE /systems/:slug/milestones/:milestoneId +Milestones give issuers the ability to award badges in recognition that the earner has earner a set of other badges. A milestone badge therefore represents higher-level achievements, 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. + +| NAME | VALUE | +|:---|:---| +| `id` | __integer__ - _id from database_ | +| `action` | __string__ - _can be `issue` or `queue-application`_ | +| `numberRequired` | __integer__ - _number of support badges required to earn the milestone badge_ | +| `primaryBadge` | __[badge](badges.md)__ - _the milestone badge itself_ | +| `supportBadges` | __array__ - _support [badges](badges.md) required to earn the milestone_ | + +## Endpoints +* [`GET /systems/:slug/milestones`](#get-systemsslugmilestones) +* [`GET /systems/:slug/milestones/:milestoneId`](#get-systemsslugmilestonesmilestoneid) +* [`POST /systems/:slug/milestones`](#post-systemsslugmilestones) +* [`PUT /systems/:slug/milestones/:milestoneId`](#put-systemsslugmilestonesmilestoneid) +* [`DELETE /systems/:slug/milestones/:milestoneId`](#delete-systemsslugmilestonesmilestoneid) + +## `GET /systems/:slug/milestones` + +Retrieve milestones within a system. + +### Expected request + +``` +GET /systems//milestones +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "milestones": [ + { + "id": 1, + "action": "issue", + "numberRequired": 3, + "primaryBadge": { + "id": 4, + "slug": "milestone-badge-slug", + "name": "Milestone Badge Name", + "strapline": "Milestone strapline.", + "earnerDescription": "Milestone earner description.", + "consumerDescription": "Milesotne consumer description.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-05-29T21:24:32.000Z", + "type": "milestone badge type", + "archived": false, + "criteriaUrl": "http://issuersite.com/milestone-badge-slug/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + "supportBadges": [ + { + "id": 1, + "slug": "support-badge-slug", + ... + }, + ... + ] + } + ] +} +``` + +#### Response structure + +* milestones `[ ]` + * id + * action + * numberRequired + * primaryBadge + * id + * slug + * strapline + * earnerDescription + * consumerDescription + * issuerUrl + * rubricUrl + * timeValue + * timeUnits + * limit + * unique + * created + * type + * archived + * criteriaUrl + * criteria `[ ]` + * categories `[ ]` + * tags `[ ]` + * milestones `[ ]` + * supportBadges `[ ]` + * id + * slug + * ... + +### Potential errors + +*None* + +## `GET /systems/:slug/milestones/:milestoneId` + +Retrieve a specific milestone using its ID. + +### Expected request + +``` +GET /systems//milestones/ +``` + +### Expected response + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "milestone": + { + "id": 1, + "action": "issue", + "numberRequired": 3, + "primaryBadge": { + "id": 4, + "slug": "milestone-badge-slug", + "name": "Milestone Badge Name", + "strapline": "Milestone strapline.", + "earnerDescription": "Milestone earner description.", + "consumerDescription": "Milesotne consumer description.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-05-29T21:24:32.000Z", + "type": "milestone badge type", + "archived": false, + "criteriaUrl": "http://issuersite.com/milestone-badge-slug/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + "supportBadges": [ + { + "id": 1, + "slug": "support-badge-slug", + ... + }, + ... + ] + } +} +``` + +#### Response structure + +* milestone + * id + * action + * numberRequired + * primaryBadge + * id + * slug + * strapline + * earnerDescription + * consumerDescription + * issuerUrl + * rubricUrl + * timeValue + * timeUnits + * limit + * unique + * created + * type + * archived + * criteriaUrl + * criteria `[ ]` + * categories `[ ]` + * tags `[ ]` + * milestones `[ ]` + * supportBadges `[ ]` + * id + * slug + * ... + +### Potential errors + +* **Milestone not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "ResourceNotFound", + "message": "Could not find milestone field: `id`, value: ``" +} +``` + +## `POST /systems/:slug/milestones` + +Create a new milestone. + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Required | Description | +|:-----------------------|-----------------|--------------------------| +| **numberRequired** | required | Integer representing how many support badges are required to earn the milestone badge. | +| **primaryBadgeId** | required | Id of primary badge which is the milestone badge. | +| **action** | optional | Can be `issue` or `queue-application`. | +| **supportBadges** | required | Array containing ids of support badges. | + +### Expected response + +``` +HTTP/1.1 201 Created +Content-Type: application/json +``` + +```json +{ + "status": "created", + "milestone": { + "id": 1, + "action": "issue", + "numberRequired": 3, + "primaryBadge": { + "id": 4, + "slug": "milestone-badge-slug", + "name": "Milestone Badge Name", + "strapline": "Milestone strapline.", + "earnerDescription": "Milestone earner description.", + "consumerDescription": "Milesotne consumer description.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-05-29T21:24:32.000Z", + "type": "milestone badge type", + "archived": false, + "criteriaUrl": "http://issuersite.com/milestone-badge-slug/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + "supportBadges": [ + { + "id": 1, + "slug": "support-badge-slug", + ... + }, + ... + ] + } +} +``` + +#### Response structure + +* status +* milestone + * id + * action + * numberRequired + * primaryBadge + * 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": "..." + }, + ... + ] + } +``` + +## `PUT /systems/:slug/milestones/:milestoneId` + +Update an existing milestone. + +### Expected request + +``` +PUT /systems//milestones/ +``` + +Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. + +| Parameters | Description | +|:-----------------------|--------------------------| +| **numberRequired** | Integer representing how many support badges are required to earn the milestone badge. | +| **primaryBadgeId** | Id of primary badge which is the milestone badge. | +| **action** | Can be `issue` or `queue-application`. | +| **supportBadges** | Array containing ids of support badges. | + +You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged. + +### 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-badge-slug", + "name": "Milestone Badge Name", + "strapline": "Milestone strapline.", + "earnerDescription": "Milestone earner description.", + "consumerDescription": "Milesotne consumer description.", + "issuerUrl": "http://issuersite.com", + "rubricUrl": "http://issuersite.com/rubric", + "timeValue": 0, + "timeUnits": "minutes", + "limit": 0, + "unique": 0, + "created": "2014-05-29T21:24:32.000Z", + "type": "milestone badge type", + "archived": false, + "criteriaUrl": "http://issuersite.com/milestone-badge-slug/criteria", + "criteria": [ ], + "categories": [ ], + "tags": [ ], + "milestones": [ ] + }, + "supportBadges": [ + { + "id": 1, + "slug": "support-badge-slug", + ... + }, + ... + ] + } +} +``` + +#### Response structure + +* status +* milestone + * id + * action + * numberRequired + * primaryBadge + * 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": "..." + }, + ... + ] + } +``` + +## `DELETE /systems/:slug/milestones/:milestoneId` + +Delete an existing milestone. + +### Expected request + +``` +DELETE /systems//milestones/ +``` + +### Expected response + +```json +{ + "status": "deleted" +} +``` + +### Potential errors + +* **Milestone not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "NotFoundError", + "message": "Could not find milestone with `id` ``" +} +``` From 333039b9b39e63cff8f513fb39c7f3c3aebb8090 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 23:28:00 +0100 Subject: [PATCH 38/61] Update milestones.md --- docs/milestones.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/milestones.md b/docs/milestones.md index 0c3cc06..da1879d 100644 --- a/docs/milestones.md +++ b/docs/milestones.md @@ -285,13 +285,13 @@ Content-Type: application/json * action * numberRequired * primaryBadge - * id - * slug - * ... + * id + * slug + * ... * supportBadges `[ ]` - * id - * slug - * ... + * id + * slug + * ... #### Potential Errors @@ -393,13 +393,13 @@ Content-Type: application/json * action * numberRequired * primaryBadge - * id - * slug - * ... + * id + * slug + * ... * supportBadges `[ ]` - * id - * slug - * ... + * id + * slug + * ... #### Potential Errors From 94e657db225cd3f40316d3f5d1c015dbe368f80e Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 23:55:35 +0100 Subject: [PATCH 39/61] Update webhooks.md --- docs/webhooks.md | 116 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 96 insertions(+), 20 deletions(-) diff --git a/docs/webhooks.md b/docs/webhooks.md index dc0397d..8f0b9c9 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -1,38 +1,114 @@ # System Callbacks (Webhooks) -## Overview +The system level object includes the configuration of a single webhook URL which will receive notifications when events occur in that system. To configure a webhook in your BadgeKit API database, add a record to the `webhooks` table, indicating the URL to send the webhook notifications to plus a secret you can use to authenticate the data received. For a more detailed overview of configuring your webhook, see [Application Review Webhooks - Configuring a Webhook](https://github.com/mozilla/badgekit-api/wiki/Application-Review-Webhooks#configuring-a-webhook). -The system level object includes the configuration of a single webhook url which will receive notifications when events occur in that system. Webhooks are configured in the [consumer model](https://github.com/mozilla/badgekit-api/blob/master/app/models/consumer.js). If you're reading this documentation and need to configure a webhook on [BadgeKit.org](http://badgekit.org) please contact your badgekit.org support person. +If you're reading this documentation and need to configure a webhook on [BadgeKit.org](http://badgekit.org) please contact your BadgeKit support person. + +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) ## Authentication -Each call to the webhook will be signed with the shared key assigned to a system. The signature works exactly like calls to the BadgeKit API. For more information, see [authorization](authorization.md). +Each call to the webhook will be signed with the key you set in your webhooks database table record. The signature works exactly like calls to the BadgeKit API. For more information, see [authorization](authorization.md). -## New Badge Instance Created +## New Application Review Submitted -Called when an instance of a badge is created (when a badge is rewarded, not when a badge class is created). +Called when a review is submitted for a badge application. The API sends the webhook the action (which will be `review`), the application data, the review data and approved status. Issuers can then process the application, responding by communicating with the earner and/or issuing the badge. -### Message -``` +Note that when a review is submitted that approves the application, the badge is NOT automatically awarded. The receiver of this webhook will have to call back to BadgeKit API to award the badge if that is the desired behavior - see [Issuing - Create a Badge Instance](issuing.md#create-a-badge-instance). _For example, you may wish to communicate with the earner for confirmation that they wish to be awarded the badge._ Similarly, the badge application will remain active and reviewable until a call is made to BadgeKit API that sets a `processed` timestamp on the application - see [Assessment - Update an Application](assessment.md#update-an-application). + +### Example Message + +```json { - action: 'award', - uid: {unique badge instance 'slug'}, - email: {email of the awardee}, - assertionUrl: {assertion url}, - issuedOn: {date / time of issuance}, + "action": "review", + "application": + { + "id": 123, + "slug": "abcdefg1234567", + "learner": "earner@adomain.com", + "created": "2014-05-12T15:13:07.000Z", + "assignedTo": null, + "assignedExpiration": null, + "badge": + { + "id": 61, + "slug": "badge-slug", + ... + }, + + "processed": null, + "evidence": [ ] + }, + + "review": + { + "id": 456, + "slug": "1234567abcdefg", + "author": "reviewer@adomain.com", + "comment": "Comment from reviewer to earner.", + "reviewItems": + [ + { + "criterionId": 221, + "satisfied": 1, + "comment": "Exactly right." + }, + ... + ] + }, + + "approved": true } ``` -## New Application Review Submitted +#### Message structure -Called when a review is submitted for a badge application. Note that when a review is submitted that approves the application, the badge is NOT automatically awarded. The receiver of this webhook will have to immediately call back to BadgeKit API to award the badge if that is the desired behavior. Similarly, the badge application will remain active and reviewable until a call is made to BadgeKit API that sets a 'processed' timestamp on the application. +* action +* [application](assessment.md#applications) + * [badge](badges.md) +* [review](assessment.md#reviews) +* approved -### Message -``` +## New Badge Instance Created + +In BadgeKit, issuing a badge to an earner means creating a [badge instance](issuing.md#create-a-badge-instance). When a badge instance is created, the API sends a message to the webhook including the details of the badge instance and assertion. The message includes the action (which will be `award`), the UID, the badge awarded, the earner email, the assertion URL, the date issued and an optional comment. + +### Example Message + +```json { - action: 'review', - application: {application object} - review: {review object} - approved: {true/false, indicating whether the application was approved} + "action": "award", + "uid": "abcdefghijkl123456789098", + "badge": + { + "id": 11, + "slug": "badge-slug", + ... + }, + + "email": "anearner@adomain.com", + "assertionUrl": "http://issuersite.com/public/assertions/abcdefghijkl123456789098", + "issuedOn": 1400094712, + "comment": null } ``` + +#### Message structure + +* action +* uid +* [badge](badges.md) +* email +* assertionUrl +* issuedOn +* comment + +## Guides + +For more on handling the webhook data, see the following pages in the BadgeKit API wiki: + +* [Application Review Webhooks](https://github.com/mozilla/badgekit-api/wiki/Application-Review-Webhooks) +* [Badge Issued Webhooks](https://github.com/mozilla/badgekit-api/wiki/Badge-Issued-Webhooks). From 501fec3fde7eacc28c3a49d6f6b306876459c185 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Thu, 29 May 2014 23:58:17 +0100 Subject: [PATCH 40/61] Update webhooks.md --- docs/webhooks.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/webhooks.md b/docs/webhooks.md index 8f0b9c9..c9a32ee 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -76,6 +76,8 @@ Note that when a review is submitted that approves the application, the badge is In BadgeKit, issuing a badge to an earner means creating a [badge instance](issuing.md#create-a-badge-instance). When a badge instance is created, the API sends a message to the webhook including the details of the badge instance and assertion. The message includes the action (which will be `award`), the UID, the badge awarded, the earner email, the assertion URL, the date issued and an optional comment. +The `award` action webhook is sent whenever a badge is issued, whether this involves an application/ review process, a claim code or a badge being issued directly to an email address. This allows issuers to carry out follow-up tasks with the earner, such as offering to push a new badge to a backpack. + ### Example Message ```json @@ -111,4 +113,4 @@ In BadgeKit, issuing a badge to an earner means creating a [badge instance](issu For more on handling the webhook data, see the following pages in the BadgeKit API wiki: * [Application Review Webhooks](https://github.com/mozilla/badgekit-api/wiki/Application-Review-Webhooks) -* [Badge Issued Webhooks](https://github.com/mozilla/badgekit-api/wiki/Badge-Issued-Webhooks). +* [Badge Issued Webhooks](https://github.com/mozilla/badgekit-api/wiki/Badge-Issued-Webhooks) From 9302e7081666605b5310135ed41a967125cece4a Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 10:24:09 +0100 Subject: [PATCH 41/61] Update assessment.md --- docs/assessment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/assessment.md b/docs/assessment.md index 046b012..47e27f2 100644 --- a/docs/assessment.md +++ b/docs/assessment.md @@ -478,7 +478,7 @@ Content-Type: application/json ### Potential errors -* **Issuer not found** +* **Application not found** ``` HTTP/1.1 404 Not Found @@ -602,7 +602,7 @@ Content-Type: application/json ### Potential errors -* **Issuer not found** +* **Review not found** ``` HTTP/1.1 404 Not Found @@ -842,7 +842,7 @@ Content-Type: application/json ### Potential errors -* **Program not found** +* **Review not found** ``` HTTP/1.1 404 Not Found From 4c842cb0feae7bc5452c9726f553c3b16bd03410 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 10:59:25 +0100 Subject: [PATCH 42/61] Update assessment.md --- docs/assessment.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/assessment.md b/docs/assessment.md index 47e27f2..d983880 100644 --- a/docs/assessment.md +++ b/docs/assessment.md @@ -236,7 +236,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find application field: `slug`, value: ``" + "message": "Could not find application field: `slug`, value: " } ``` @@ -488,7 +488,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find application field: `slug`, value: ``" + "message": "Could not find application field: `slug`, value: " } ``` @@ -612,7 +612,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find review field: `slug`, value ``" + "message": "Could not find review field: `slug`, value " } ``` @@ -852,6 +852,6 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find review field: `slug`, value: ``" + "message": "Could not find review field: `slug`, value: " } ``` From 1d3a5fde825ba3e760892dc74826e6152a55f428 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:01:00 +0100 Subject: [PATCH 43/61] Update badges.md --- docs/badges.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index 55a8295..4776e73 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -279,7 +279,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find badge field: `slug`, value: ``" + "message": "Could not find badge field: `slug`, value: " } ``` @@ -707,6 +707,6 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find badge field: `slug`, value: ``" + "message": "Could not find badge field: `slug`, value: " } ``` From 918320829774f1d3b5e95a4399e8152c8175a03f Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:02:10 +0100 Subject: [PATCH 44/61] Update claim-codes.md --- docs/claim-codes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/claim-codes.md b/docs/claim-codes.md index bc06e03..14a92f6 100644 --- a/docs/claim-codes.md +++ b/docs/claim-codes.md @@ -149,7 +149,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find the request claim code: ``" + "message": "Could not find the request claim code: " } ``` @@ -222,7 +222,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find the request claim code: ``" + "message": "Could not find the request claim code: " } ``` @@ -449,7 +449,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find claimCode field: `code`, value: ``" + "message": "Could not find claimCode field: `code`, value: " } ``` @@ -531,6 +531,6 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find claimCode field: `code`, value: ``" + "message": "Could not find claimCode field: `code`, value: " } ``` From 1b56ee89129725091d5acfd3568198a782d29a41 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:03:06 +0100 Subject: [PATCH 45/61] Update issuers.md --- docs/issuers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/issuers.md b/docs/issuers.md index 5c03d25..90cd976 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -150,7 +150,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find issuer field: `slug`, value ``" + "message": "Could not find issuer field: `slug`, value " } ``` @@ -416,6 +416,6 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find issuer field: `slug`, value: ``" + "message": "Could not find issuer field: `slug`, value: " } ``` From 6caf3dc8f1fab0d81acfdbbb8887438afec13349 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:05:38 +0100 Subject: [PATCH 46/61] Update milestones.md --- docs/milestones.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/milestones.md b/docs/milestones.md index da1879d..b89a8c1 100644 --- a/docs/milestones.md +++ b/docs/milestones.md @@ -211,8 +211,8 @@ Content-Type: application/json ```json { - "code": "ResourceNotFound", - "message": "Could not find milestone field: `id`, value: ``" + "code": "NotFoundError", + "message": "Could not find milestone with `id` " } ``` @@ -454,6 +454,6 @@ Content-Type: application/json ```json { "code": "NotFoundError", - "message": "Could not find milestone with `id` ``" + "message": "Could not find milestone with `id` " } ``` From 8d583b7bc611ee0c5ca128f28cc9e1891856ea4b Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:06:37 +0100 Subject: [PATCH 47/61] Update programs.md --- docs/programs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/programs.md b/docs/programs.md index c437f6e..fa70f1a 100644 --- a/docs/programs.md +++ b/docs/programs.md @@ -122,7 +122,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find program field: `slug`, value: ``" + "message": "Could not find program field: `slug`, value: " } ``` @@ -358,6 +358,6 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find program field: `slug`, value: ``" + "message": "Could not find program field: `slug`, value: " } ``` From e9c12248eec85a2cc622886dca02a3ae013d9236 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:07:40 +0100 Subject: [PATCH 48/61] Update systems.md --- docs/systems.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/systems.md b/docs/systems.md index 4a8c4e9..ddf830d 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -409,7 +409,7 @@ Content-Type: application/json ```json { "code": "ResourceNotFound", - "message": "Could not find system with slug ``" + "message": "Could not find system with slug " } ``` From e490b239b08b93a316b3ab46dcaa227195c27fe8 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:26:47 +0100 Subject: [PATCH 49/61] Update issuing.md --- docs/issuing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/issuing.md b/docs/issuing.md index adaede9..223332b 100644 --- a/docs/issuing.md +++ b/docs/issuing.md @@ -181,9 +181,9 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` |:-----------------------|-----------------|--------------------------| | **email** | required | The email address for the earner the badge is being issued to. | | **claimCode** | optional | A claim code for the badge. | -| **slug** | optional | Instance slug. | -| **issuedOn** | optional | Date issued. | -| **expires** | optional | Date instance expires. | +| **slug** | optional | Instance slug. (API will generate if not provided.) | +| **issuedOn** | optional | Timestamp representing date issued. (API will generate if not provided.) | +| **expires** | optional | Timestamp representing date instance expires. | ### Expected response From 6d90bbaa8dc6e5404b633a79b2ae3ed33a498493 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:31:35 +0100 Subject: [PATCH 50/61] Update badges.md --- docs/badges.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index 4776e73..5571d86 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -301,18 +301,18 @@ POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/ |:-----------------------|-----------------|--------------------------| | **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. -| **strapline** | _optional_ | Short tagline style description of the badge. Maximum 140 characters. +| **image** OR **imageUrl** | _required_ | Image for the program. Should be either multipart data or a URL. +| **unique** | _required_ | Boolean indicator of badge uniqueness. +| **criteriaUrl** | _required_ | Link to badge criteria. | **earnerDescription** | _required_ | Description of the badge for potential earners. | **consumerDescription** | _required_ | Description of the badge for consumers viewing it. +| **strapline** | _optional_ | Short tagline style description of the badge. Maximum 140 characters. | **issuerUrl** | _optional_ | URL for badge issuer. | **rubricUrl** | _optional_ | Link to any rubric material associated with the badge. | **timeValue** | _optional_ | Badges can be associated with a time limit for earning. | **timeUnits** | _optional_ | Time values can be expressed as `minutes`, `hours`, `days` or `weeks`. | **limit** | _optional_ | Badges can be awarded to a fixed maximum number of earners. -| **unique** | _required_ | Boolean indicator of badge uniqueness. -| **image** OR **imageUrl** | _required_ | Image for the program. Should be either multipart data or a URL. | **archived** | _optional_ | Boolean indicating archived status for badge. -| **criteriaUrl** | _required_ | Link to badge criteria. | **criteria** | _optional_ | Array of criteria items - each criteria should include `description` and `required` status plus optional `note` for badge reviewers. | **type** | _required_ | Short string representing badge type. Maximum 255 characters. | **categories** | _optional_ | Array of category names for the badge. @@ -647,6 +647,20 @@ Content-Type: application/json } ``` +* **Badge not found** + +``` + HTTP/1.1 404 Not Found + Content-Type: application/json +``` + +```json + { + "code": "ResourceNotFound", + "message": "Could not find badge field: `slug`, value: " + } +``` + ## Delete a Badge Deletes an existing badge. From 96db2bd7d281134970207675c4badf4307ef0879 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:49:43 +0100 Subject: [PATCH 51/61] Update README.md --- docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 19543f1..fc5bc35 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # BadgeKit API Documentation -The BadgeKit API docs include the information you need to get started using the endpoints and webhooks. The docs are as follows: +The BadgeKit API docs include the information you need to get started using the endpoints and webhooks. The docs are structured as follows: * [API Endpoints](api-endpoints.md) * Containers: @@ -16,9 +16,9 @@ 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 it 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 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, together with sample code excerpts, in the [BadgeKit API wiki](https://github.com/mozilla/badgekit-api/wiki): +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): * [Using BadgeKit API](https://github.com/mozilla/badgekit-api/wiki/Using-BadgeKit-API) * [Retrieving Badges](https://github.com/mozilla/badgekit-api/wiki/Retrieving-Badges) From ac984a780d084e1a72c93d1e025b1c643d7a3223 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 11:54:14 +0100 Subject: [PATCH 52/61] Update api-endpoints.md Commenting out `public` endpoints. --- docs/api-endpoints.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md index da20287..4c19411 100644 --- a/docs/api-endpoints.md +++ b/docs/api-endpoints.md @@ -1,6 +1,6 @@ # API Endpoints -See the following overview of the available BadgeKit API endpoints - browse to the linked docs for each object/ process for more detailed information. +See the following overview of the available BadgeKit API endpoints - browse to the linked docs in each section for more detailed information. * Containers * [Systems](systems.md) @@ -9,21 +9,18 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **GET** /systems/:slug * **PUT** /systems/:slug * **DELETE** /systems/:slug - * **GET** /public/systems/:slug * [Issuers](issuers.md) * **GET** /systems/:slug/issuers * **POST** /systems/:slug/issuers * **GET** /systems/:slug/issuers/:slug * **PUT** /systems/:slug/issuers/:slug * **DELETE** /systems/:slug/issuers/:slug - * **GET** /public/systems/:slug/issuers/:slug * [Programs](programs.md) * **GET** /systems/:slug/issuers/:slug/programs * **POST** /systems/:slug/issuers/:slug/programs * **GET** /systems/:slug/issuers/:slug/programs/:slug * **PUT** /systems/:slug/issuers/:slug/programs/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug - * **GET** /public/systems/:slug/issuers/:slug/programs/:slug * Badge Management * [Badges](badges.md) (can belong directly to a system, issuer or program) * **GET** /systems/:slug/badges @@ -79,7 +76,6 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **DELETE** /systems/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/instances/:email * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email - * **GET** /public/assertions/:slug * [Assessment](assessment.md) (managing earner applications for badges) * **GET** /systems/:slug/applications * **GET** /systems/:slug/issuers/:slug/applications @@ -114,8 +110,6 @@ See the following overview of the available BadgeKit API endpoints - browse to t * **DELETE** /systems/:slug/badges/:slug/applications/:slug/reviews/:slug * **DELETE** /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug - * Images - * **GET** /public/images/:imageId * [Milestones](milestones.md) * **GET** /systems/:slug/milestones * **POST** /systems/:slug/milestones @@ -124,3 +118,11 @@ 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). + + From 15a574c7bb45d2b5e45d9f005babbe26d14ede75 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 12:12:51 +0100 Subject: [PATCH 53/61] Update assessment.md --- docs/assessment.md | 59 ++++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/docs/assessment.md b/docs/assessment.md index d983880..6579787 100644 --- a/docs/assessment.md +++ b/docs/assessment.md @@ -1,6 +1,8 @@ # Assessment -Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting reviews. When a review is submitted, issuers can detect this at their [webhook](webhooks.md). Typically an issuer will respond to an approved review by offering the earner the badge, creating a [badge instance](issuing.md) and marking the application as processed using the updating endpoint below. +Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting their reviews. When a review is submitted, issuers can detect this at their [webhook](webhooks.md). Typically an issuer will respond to an approved review by offering the earner the badge, creating a [badge instance](issuing.md) and marking the application as processed using the updating endpoint below. + +Assessment therefore involves two objects in BadgeKit API: applications and reviews. ## Applications @@ -10,11 +12,11 @@ Badges can be issued following assessment of earner applications. Issuers can al | `slug` | __string__ | | `learner` | __email address__ - _earner email_ | | `created` | __timestamp__ | -| `assignedTo` | __string__ _email login for assigned reviewer_ | +| `assignedTo` | __string__ - _email login for assigned reviewer_ | | `assignedExpiration` | __timestamp__ | | `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)_ | +| `evidence` | __array__ - _each evidence item can include: `url`, `mediaType` (which can be `image` or `link`) and `reflection` (which is a string)_ | ## Reviews @@ -24,7 +26,7 @@ Badges can be issued following assessment of earner applications. Issuers can al | `slug` | __string__ | | `author` | __email address__ - _reviewer email_ | | `comment` | __string__ - _applicant feedback_ | -| `reviewItems` | __array__ - _one for each criteria item for badge, each reviewItem can include `criterionId` for badge criteria, `satisfied` status and `comment`_ | +| `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 @@ -257,8 +259,8 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` | Parameters | Required | Description | |:-----------------------|-----------------|--------------------------| | **learner** | required | The email address for the earner applying. | -| **evidence** | optional | Array including evidence items - each item can include `reflection`, `mediaType` and/or `url`. | -| **assignedTo** | optional | Reviewer application is assigned to. | +| **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. | ### Expected response @@ -291,7 +293,8 @@ Content-Type: application/json "url": "http://awebsite.com/page", "mediaType": "link", "reflection": "I did great stuff." - } + }, + ... ] } } @@ -354,8 +357,8 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded` | Parameters | Description | |:-----------------------|--------------------------| | **learner** | The email address for the earner applying. | -| **evidence** | Array including evidence items - each item can include `reflection`, `mediaType` and/or `url`. | -| **assignedTo** | Reviewer application is assigned to. | +| **evidence** | Array including evidence items - each item can include `reflection`, `mediaType` and `url`. | +| **assignedTo** | Email of reviewer application is assigned to. | | **assignedExpiration** | Expiry date. | | **processed** | Timestamp indicating application has been processed. | @@ -494,7 +497,7 @@ Content-Type: application/json ## Retrieve Application Reviews -Retrieve reviews for applications. +Retrieve reviews for specific applications. ### Expected request @@ -522,7 +525,7 @@ Content-Type: application/json "reviewItems": [ { "criterionId": 1, - "satisfied": 0, + "satisfied": 1, "comment": "perfect" }, ... @@ -551,7 +554,7 @@ Content-Type: application/json ## Retrieve a Specific Review -Retrieve a specific application review for a badge. +Retrieve a specific application review. ### Expected request @@ -579,7 +582,7 @@ Content-Type: application/json "reviewItems": [ { "criterionId": 1, - "satisfied": 0, + "satisfied": 1, "comment": "perfect" }, ... @@ -618,7 +621,7 @@ Content-Type: application/json ## Submit an Application Review -Post a review for an application. +Post a review for a specific application. ### Expected request @@ -655,7 +658,7 @@ Content-Type: application/json "reviewItems": [ { "criterionId": 1, - "satisfied": 0, + "satisfied": 1, "comment": "perfect" }, ... @@ -674,9 +677,9 @@ Content-Type: application/json * author * comment * reviewItems `[ ]` - * criterionId - * satisfied - * comment + * criterionId + * satisfied + * comment ### Potential errors @@ -704,7 +707,7 @@ Content-Type: application/json ## Update a Review -Update an existing application review for a badge. +Update an existing application review. ### Expected request @@ -742,7 +745,7 @@ Content-Type: application/json "reviewItems": [ { "criterionId": 1, - "satisfied": 0, + "satisfied": 1, "comment": "perfect" }, ... @@ -760,9 +763,9 @@ Content-Type: application/json * author * comment * reviewItems `[ ]` - * criterionId - * satisfied - * comment + * criterionId + * satisfied + * comment ### Potential errors @@ -790,7 +793,7 @@ Content-Type: application/json ## Delete a Review -Delete an existing application review for a badge. +Delete an existing application review. ### Expected request @@ -818,7 +821,7 @@ Content-Type: application/json "reviewItems": [ { "criterionId": 1, - "satisfied": 0, + "satisfied": 1, "comment": "perfect" }, ... @@ -836,9 +839,9 @@ Content-Type: application/json * author * comment * reviewItems `[ ]` - * criterionId - * satisfied - * comment + * criterionId + * satisfied + * comment ### Potential errors From f8e23f0f05c963be78e168371cc5289576c845ca Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 12:36:40 +0100 Subject: [PATCH 54/61] Update badges.md --- docs/badges.md | 84 +++++++++++++++++++++++++------------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/badges.md b/docs/badges.md index 5571d86..9fed932 100644 --- a/docs/badges.md +++ b/docs/badges.md @@ -4,28 +4,28 @@ 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_ | -| `name` | __string__ | +| `id` | __integer__ - _ID from database entry._ | +| `slug` | __string__ - _Used to identify badge in API endpoints._ | +| `name` | __string__ - _Display name._ | | `strapline` | __string__ - _Short tagline description._ | | `earnerDescription` | __string__ - _Description for potential earners._ | | `consumerDescription` | __string__ - _Description for viewers of badge e.g. college admin or employer._ | | `issuerUrl` | __string__ | | `rubricUrl` | __string__ - _Link to supporting material._ | -| `timeValue` | __integer__ | +| `timeValue` | __integer__ - _Time estimate for earner to complete badge._ | | `timeUnits` | __enum__ - _Can be `minutes`, `hours`, `days` or `weeks`._ | -| `limit` | __integer__ - _Optional limit for number of times badge can be earned._ | -| `unique` | __boolean__ | +| `limit` | __integer__ - _Limit for number of people who can earn the badge._ | +| `unique` | __boolean__ - _True if the same earner can only earn the badge once._ | | `created` | __timestamp__ | -| `imageUrl` | __string__ | -| `type` | __string__ | -| `archived` | __boolean__ | +| `imageUrl` | __string__ - _Badge display image._ | +| `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._ | -| `criteriaUrl` | __string__ | -| `criteria` | __array__ - _Includes `id`, `description`, `required` status and `note`._ | -| `categories` | __array__ - _Each category is a string._ | -| `tags` | __array__- _Each tag is a string._ | -| [`milestones`](milestones.md) | __array__ - _A milestone badge is awarded when a set of other badges are earned._ | +| `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._ | +| `tags` | __array__- _Tags can be used to aid search and discovery of badges._ | +| [`milestones`](milestones.md) | __array__ - _A milestone badge is awarded when a set of other badges is earned._ | ## Endpoints @@ -52,14 +52,14 @@ A badge represents the generic data for an earnable badge (not an awarded badge, ## Retrieve Badge List -Retrieves all available badges, filtered by system, issuer or program. +Retrieves badges, filtered by system, issuer or program. ### Expected request ``` -GET /systems/:systemSlug/badges HTTP/1.1 -GET /systems/:systemSlug/issuers/:issuerSlug/badges HTTP/1.1 -GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/1.1 +GET /systems/:systemSlug/badges +GET /systems/:systemSlug/issuers/:issuerSlug/badges +GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges ``` #### Available request parameters @@ -143,14 +143,14 @@ Content-Type: application/json * imageUrl * type * archived - * system `[ ]` + * [system](systems.md) `[ ]` * id * slug * url * name * email * imageUrl - * issuers `[ ]` + * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -159,7 +159,7 @@ Content-Type: application/json * note * categories `[ ]` * tags `[ ]` - * milestones `[ ]` + * [milestones](milestones.md) `[ ]` ### Potential errors @@ -173,9 +173,9 @@ Retrieves a specific badge using its slug. ### Expected request ``` -GET /systems/:systemSlug/badges/:badgeSlug HTTP/1.1 -GET /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug HTTP/1.1 -GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug HTTP/1.1 +GET /systems/:systemSlug/badges/:badgeSlug +GET /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug +GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug ``` ### Expected response @@ -249,14 +249,14 @@ Content-Type: application/json * imageUrl * type * archived - * system `[ ]` + * [system](systems.md) `[ ]` * id * slug * url * name * email * imageUrl - * issuers `[ ]` + * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -265,7 +265,7 @@ Content-Type: application/json * note * categories `[ ]` * tags `[ ]` - * milestones `[ ]` + * [milestones](milestones.md) `[ ]` ### Potential errors @@ -283,7 +283,7 @@ Content-Type: application/json } ``` -## `Create New Badge` +## Create New Badge Creates a new badge in a system, issuer or program (_or updates an existing badge_). @@ -292,9 +292,9 @@ Creates a new badge in a system, issuer or program (_or updates an existing badg Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. ``` -POST /systems/:systemSlug/badges HTTP/1.1 -POST /systems/:systemSlug/issuers/:issuerSlug/badges HTTP/1.1 -POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/1.1 +POST /systems/:systemSlug/badges +POST /systems/:systemSlug/issuers/:issuerSlug/badges +POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges ``` | Parameters | Required | Description | @@ -302,7 +302,7 @@ POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges HTTP/ | **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 badge uniqueness. +| **unique** | _required_ | Boolean indicator of whether an earner can earn the badge only once. | **criteriaUrl** | _required_ | Link to badge criteria. | **earnerDescription** | _required_ | Description of the badge for potential earners. | **consumerDescription** | _required_ | Description of the badge for consumers viewing it. @@ -392,14 +392,14 @@ Content-Type: application/json * imageUrl * type * archived - * system `[ ]` + * [system](systems.md) `[ ]` * id * slug * url * name * email * imageUrl - * issuers `[ ]` + * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -408,7 +408,7 @@ Content-Type: application/json * note * categories `[ ]` * tags `[ ]` - * milestones `[ ]` + * [milestones](milestones.md) `[ ]` ### Potential errors @@ -482,18 +482,18 @@ PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badge |:-----------------------|--------------------------| | **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. -| **strapline** | Short tagline style description of the badge. Maximum 140 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. +| **criteriaUrl** | Link to badge criteria. | **earnerDescription** | Description of the badge for potential earners. | **consumerDescription** | Description of the badge for consumers viewing it. +| **strapline** | Short tagline style description of the badge. Maximum 140 characters. | **issuerUrl** | URL for badge issuer. | **rubricUrl** | Link to any rubric material associated with the badge. | **timeValue** | Badges can be associated with a time limit for earning. | **timeUnits** | Time values can be expressed as `minutes`, `hours`, `days` or `weeks`. | **limit** | Badges can be awarded to a fixed maximum number of earners. -| **unique** | Boolean indicator of badge uniqueness. -| **image** OR **imageUrl** | Image for the program. Should be either multipart data or a URL. | **archived** | Boolean indicating archived status for badge. -| **criteriaUrl** | Link to badge criteria. | **criteria** | Array of criteria items - each criteria should include `description` and `required` status plus optional `note` for badge reviewers. | **type** | Short string representing badge type. Maximum 255 characters. | **categories** | Array of category names for the badge. @@ -575,14 +575,14 @@ Content-Type: application/json * imageUrl * type * archived - * system `[ ]` + * [system](systems.md) `[ ]` * id * slug * url * name * email * imageUrl - * issuers `[ ]` + * [issuers](issuers.md) `[ ]` * criteriaUrl * criteria `[ ]` * id @@ -591,7 +591,7 @@ Content-Type: application/json * note * categories `[ ]` * tags `[ ]` - * milestones `[ ]` + * [milestones](milestones.md) `[ ]` ### Potential errors From 2aca019b68bacedf07b382c796de48ee0d04a7a7 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 12:43:30 +0100 Subject: [PATCH 55/61] Update claim-codes.md --- docs/claim-codes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/claim-codes.md b/docs/claim-codes.md index 14a92f6..c8bb27c 100644 --- a/docs/claim-codes.md +++ b/docs/claim-codes.md @@ -44,7 +44,7 @@ Earners can use claim codes to claim badges. For example, a claim code can be di ## Retrieve Claim Codes -Retrieves all claim codes for a badge within a system, issuer or program/. +Retrieves all claim codes for a badge within a system, issuer or program. ### Expected request @@ -384,7 +384,7 @@ Delete a claim code. ``` DELETE /systems/:systemSlug/badges/:badgeSlug/codes/:code -DELETE /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug +DELETE /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug/codes/:code DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug/codes/:code ``` From 485c70d8ebc2fef197c9cdd70af2f3bdabce2feb Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 12:49:38 +0100 Subject: [PATCH 56/61] Update issuers.md --- docs/issuers.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/issuers.md b/docs/issuers.md index 90cd976..36dfd01 100644 --- a/docs/issuers.md +++ b/docs/issuers.md @@ -4,14 +4,14 @@ Issuers represent mid-level admin in BadgeKit. Each issuer belongs to a single [ | NAME | VALUE | |:---|:---| -| `id` | integer - _id from database entry_ | -| `slug` | string - _used to identify issuer in API endpoints_ | -| `url` | string | -| `name` | string | -| `description` | string | -| `email` | string | -| `imageUrl` | string | -| `programs` | array - _[programs](programs.md) in the issuer_ | +| `id` | integer - _ID from database entry._ | +| `slug` | string - _Short, computer-friendly name for the issuer. Used to identify issuer in API endpoints._ | +| `url` | string - _Issuer URL._ | +| `name` | string - _Name of the issuer._ | +| `description` | string - _A short, human-friendly description of the issuer._ | +| `email` | string - _Email address associated with the badge administrator of the issuer._ | +| `imageUrl` | string - _Image for the issuer._ | +| `programs` | array - _[Programs](programs.md) in the issuer._ | ## Endpoints @@ -28,7 +28,7 @@ Retrieves all available issuers in the specified system. ### Expected request ``` -GET /systems/:systemSlug/issuers HTTP/1.1 +GET /systems/:systemSlug/issuers ``` ### Expected response @@ -90,7 +90,7 @@ Retrieves a specific issuer using its slug. ### Expected request ``` -GET /systems/:systemSlug/issuers/:issuerSlug HTTP/1.1 +GET /systems/:systemSlug/issuers/:issuerSlug ``` ### Expected response @@ -161,7 +161,7 @@ Creates a new issuer. ### Expected request ``` -POST /systems/:systemSlug/issuers` +POST /systems/:systemSlug/issuers ``` Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. @@ -220,7 +220,7 @@ Content-Type: application/json * description * email * imageUrl - * programs `[ ]` + * [programs](programs.md) `[ ]` ### Potential errors @@ -324,7 +324,7 @@ Content-Type: application/json * description * email * imageUrl - * programs `[ ]` + * [programs](programs.md) `[ ]` ### Potential errors @@ -378,7 +378,7 @@ Deletes an existing issuer. ### Expected request ``` -DELETE /systems/:systemSlug/issuers/:issuerSlug HTTP/1.1 +DELETE /systems/:systemSlug/issuers/:issuerSlug ``` ### Expected response From c2a5e2d029945203e8fc881b48bf4da20717ed28 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 12:56:55 +0100 Subject: [PATCH 57/61] Update milestones.md --- docs/milestones.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/milestones.md b/docs/milestones.md index b89a8c1..97ea791 100644 --- a/docs/milestones.md +++ b/docs/milestones.md @@ -1,6 +1,6 @@ # Milestones -Milestones give issuers the ability to award badges in recognition that the earner has earner a set of other badges. A milestone badge therefore represents higher-level achievements, 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. +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. | NAME | VALUE | |:---|:---| @@ -82,7 +82,7 @@ Content-Type: application/json * id * action * numberRequired - * primaryBadge + * primaryBadge ([badge](badges.md)) * id * slug * strapline @@ -175,7 +175,7 @@ Content-Type: application/json * id * action * numberRequired - * primaryBadge + * primaryBadge ([badge](badges.md)) * id * slug * strapline @@ -220,12 +220,18 @@ Content-Type: application/json Create a new milestone. +### Expected request + +``` +POST /systems//milestones +``` + Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. | Parameters | Required | Description | |:-----------------------|-----------------|--------------------------| | **numberRequired** | required | Integer representing how many support badges are required to earn the milestone badge. | -| **primaryBadgeId** | required | Id of primary badge which is the milestone badge. | +| **primaryBadgeId** | required | Id of primary badge, which is the milestone badge itself. | | **action** | optional | Can be `issue` or `queue-application`. | | **supportBadges** | required | Array containing ids of support badges. | @@ -284,7 +290,7 @@ Content-Type: application/json * id * action * numberRequired - * primaryBadge + * primaryBadge ([badge](badges.md)) * id * slug * ... @@ -392,7 +398,7 @@ Content-Type: application/json * id * action * numberRequired - * primaryBadge + * primaryBadge ([badge](badges.md)) * id * slug * ... @@ -424,6 +430,20 @@ Content-Type: application/json } ``` +* **Milestone not found** + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +``` + +```json +{ + "code": "NotFoundError", + "message": "Could not find milestone with `id` " +} +``` + ## `DELETE /systems/:slug/milestones/:milestoneId` Delete an existing milestone. From f36a17581e82ab60aa1aaa2b16a8e7c5ee972efc Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 13:00:31 +0100 Subject: [PATCH 58/61] Update programs.md --- docs/programs.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/programs.md b/docs/programs.md index fa70f1a..242fe29 100644 --- a/docs/programs.md +++ b/docs/programs.md @@ -1,16 +1,16 @@ # Programs -Programs represent the last level of badging admin in BadgeKit. Each program belongs to one [issuer](issuers.md), optionally along with other programs. Badges can be associated with a program, which could be a program of events grouping activities on a theme or subject area. +Programs represent the lowest level of badging admin in BadgeKit. Each program belongs to one [issuer](issuers.md), optionally along with other programs. Badges can be associated with a program, which could be a program of events grouping activities on a theme or subject area. | NAME | VALUE | |:---|:---| -| `id` | integer - _id from database entry_ | -| `slug` | string - _used to identify program in API endpoints_ | -| `url` | string | -| `name` | string | -| `description` | string | -| `email` | string | -| `imageUrl` | string | +| `id` | integer - _ID from database entry._ | +| `slug` | string - _Short, computer-friendly name for the program. Used to identify program in API endpoints_ | +| `url` | string - _URL for the program._ | +| `name` | string - _Name of the program._ | +| `description` | string - _A short, human-friendly description of the program._ | +| `email` | string - _Email address associated with the badge administrator of the program._ | +| `imageUrl` | string - _Image for the program._ | ## Endpoints @@ -27,7 +27,7 @@ Retrieves all available programs in the specified system and issuer. ### Expected request ``` -GET /systems/:systemSlug/issuers/:issuerSlug/programs HTTP/1.1 +GET /systems/:systemSlug/issuers/:issuerSlug/programs ``` ### Expected response @@ -75,7 +75,7 @@ Retrieves a specific program using its slug. ### Expected request ``` -GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 +GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug ``` ### Expected response @@ -133,7 +133,7 @@ Creates a new program. ### Expected request ``` -POST /systems/:systemSlug/issuers/:issuerSlug/programs HTTP/1.1 +POST /systems/:systemSlug/issuers/:issuerSlug/programs ``` Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. @@ -233,7 +233,7 @@ Updates an existing program. ### Expected request ``` -PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 +PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug ``` Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. @@ -263,7 +263,7 @@ Content-Type: application/json "id": 1, "slug": "program-slug", "url": "http://programsite.com", - "name": Updated Program Name", + "name": "Updated Program Name", "description": "Updated program description.", "email": "admin@programsite.com", "imageUrl": "http://programsite.com/image.jpg" @@ -323,7 +323,7 @@ Deletes an existing program. ### Expected request ``` -DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug HTTP/1.1 +DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug ``` ### Expected response From 835a24892268b9a5168db11689446a30421c5cf9 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 13:04:32 +0100 Subject: [PATCH 59/61] Update systems.md --- docs/systems.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/systems.md b/docs/systems.md index ddf830d..1f37db7 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -4,13 +4,14 @@ A system represents the top admin level within BadgeKit - an instance can contai | NAME | VALUE | |:---|:---| -| `id` | integer - _id from database entry_ | -| `slug` | string - _used to identify system in API endpoints_ | -| `url` | string | -| `name` | string | -| `email` | string | -| `imageUrl` | string | -| `issuers` | array - _[issuers](issuers.md) in the system (may contain [programs](programs.md))_ | +| `id` | integer - _ID from database entry._ | +| `slug` | string - _Short, computer-friendly name for the system. Used to identify system in API endpoints._ | +| `url` | string - _URL for the system._ | +| `name` | string - _Name of the system._ | +| `description` | string - _A short, human-friendly description of the system._ | +| `email` | string - _Email address associated with the badge administrator of the system._ | +| `imageUrl` | string - _Image for the system._ | +| `issuers` | array - _[Issuers](issuers.md) in the system (may contain [programs](programs.md))._ | ## Endpoints @@ -27,7 +28,7 @@ Retrieves all available systems in the BadgeKit API instance. ### Expected request ``` -GET /systems HTTP/1.1 +GET /systems ``` ### Expected response @@ -100,7 +101,7 @@ Retrieves a specific system using its slug. ### Expected request ``` -GET /systems/:systemSlug HTTP/1.1 +GET /systems/:systemSlug ``` ### Expected response @@ -228,7 +229,7 @@ Content-Type: application/json * url * email * imageUrl - * issuers `[ ]` + * [issuers](issuers.md) `[ ]` ### Potential errors @@ -372,7 +373,7 @@ Deletes an existing system. ### Expected request ``` -DELETE /systems/:systemSlug HTTP/1.1 +DELETE /systems/:systemSlug ``` ### Expected response @@ -412,7 +413,8 @@ Content-Type: application/json "message": "Could not find system with slug " } ``` - + From 8a09541ed62c7218277c307267d23ca50193f422 Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 13:07:59 +0100 Subject: [PATCH 60/61] Update webhooks.md --- docs/webhooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/webhooks.md b/docs/webhooks.md index c9a32ee..91b30c4 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -1,6 +1,6 @@ # System Callbacks (Webhooks) -The system level object includes the configuration of a single webhook URL which will receive notifications when events occur in that system. To configure a webhook in your BadgeKit API database, add a record to the `webhooks` table, indicating the URL to send the webhook notifications to plus a secret you can use to authenticate the data received. For a more detailed overview of configuring your webhook, see [Application Review Webhooks - Configuring a Webhook](https://github.com/mozilla/badgekit-api/wiki/Application-Review-Webhooks#configuring-a-webhook). +The system level object includes the configuration of a single webhook URL which will receive notifications when events occur in that system. To configure a webhook in your BadgeKit API database, add a record to the `webhooks` table, indicating the URL to send the webhook notifications to, plus a secret you can use to authenticate the data received. For a more detailed overview of configuring your webhook, see [Application Review Webhooks - Configuring a Webhook](https://github.com/mozilla/badgekit-api/wiki/Application-Review-Webhooks#configuring-a-webhook). If you're reading this documentation and need to configure a webhook on [BadgeKit.org](http://badgekit.org) please contact your BadgeKit support person. @@ -83,7 +83,7 @@ The `award` action webhook is sent whenever a badge is issued, whether this invo ```json { "action": "award", - "uid": "abcdefghijkl123456789098", + "uid": "abcdefghijkl1234567890", "badge": { "id": 11, @@ -92,7 +92,7 @@ The `award` action webhook is sent whenever a badge is issued, whether this invo }, "email": "anearner@adomain.com", - "assertionUrl": "http://issuersite.com/public/assertions/abcdefghijkl123456789098", + "assertionUrl": "http://issuersite.com/public/assertions/abcdefghijkl1234567890", "issuedOn": 1400094712, "comment": null } From af17220be96308f75b9117754a978b7efb9dff3f Mon Sep 17 00:00:00 2001 From: Sue Smith Date: Fri, 30 May 2014 13:18:31 +0100 Subject: [PATCH 61/61] Update systems.md --- docs/systems.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/systems.md b/docs/systems.md index 1f37db7..8b2e890 100644 --- a/docs/systems.md +++ b/docs/systems.md @@ -46,6 +46,7 @@ Content-Type: application/json "slug": "system-slug", "url": "http://systemsite.com", "name": "System Name", + "description": "System description.", "email": "admin@systemsite.com", "imageUrl": "http://systemsite.com/image.jpg", "issuers": [ @@ -85,6 +86,7 @@ Content-Type: application/json * slug * url * name + * description * email * imageUrl * [issuers](issuers.md) `[ ]` @@ -118,6 +120,7 @@ Content-Type: application/json "slug": "system-slug", "url": "http://systemsite.com", "name": "System Name", + "description": "System description.", "email": "admin@systemsite.com", "imageUrl": "http://systemsite.com/image.jpg", "issuers": [ @@ -155,6 +158,7 @@ Content-Type: application/json * slug * url * name + * description * email * imageUrl * [issuers](issuers.md) `[ ]` @@ -211,6 +215,7 @@ Content-Type: application/json "id": 1, "slug": "system-slug", "name": "System Name", + "description": "System description.", "url": "http://systemsite.com", "email": "admin@systemsite.com", "imageUrl": "http://systemsite.com/image.jpg", @@ -226,6 +231,7 @@ Content-Type: application/json * id * slug * name + * description * url * email * imageUrl @@ -269,6 +275,7 @@ Content-Type: application/json "details": { "slug": "system-slug", "name": "System Name", + "description": "System description.", "url": "http://systemsite.com", "email": "admin@systemsite.com", "description": "System Description" @@ -313,6 +320,7 @@ Content-Type: application/json "id": 1, "slug": "system-slug", "name": "System Name", + "description": "System description.", "url": "http://systemsite.com", "email": "admin@systemsite.com", "imageUrl": "http://systemsite.com/image.jpg", @@ -361,7 +369,7 @@ Content-Type: application/json "name": "System Name", "url": "http://systemsite.com", "email": "admin@systemsite.com", - "description": "System Description" + "description": "System description." } } ``` @@ -390,6 +398,7 @@ Content-Type: application/json "id": 1, "slug": "system-slug", "name": "System Name", + "description": "System description.", "url": "http://systemsite.com", "email": "admin@systemsite.com", "imageUrl": "http://systemsite.com/image.jpg", @@ -413,8 +422,3 @@ Content-Type: application/json "message": "Could not find system with slug " } ``` -