Doc updates to include bulk issuing

docs/api-endpoints.md

@@ -74,6 +74,9 @@ See the following overview of the available BadgeKit API endpoints - browse to t
     * **POST** /systems/:slug/badges/:slug/instances
     * **POST** /systems/:slug/issuers/:slug/badges/:slug/instances
     * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances
+    * **POST** /systems/:slug/badges/:slug/instances/bulk
+    * **POST** /systems/:slug/issuers/:slug/badges/:slug/instances/bulk
+    * **POST** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/bulk
     * **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

docs/assessment.md

@@ -91,10 +91,11 @@ GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications
 
 #### Available request parameters
 
+* **`processed`** - boolean indicating whether to return processed or unprocessed applications
 * **`page`:** - page of results to return
 * **`count`:** - count of results to return per page
 
-e.g. `/systems/<slug>/applications?count=2&page=1`
+e.g. `/systems/<slug>/applications?processed=true&count=2&page=1`
 
 ### Expected response
 

docs/authorization.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Authorization is done by generating a JWT token for each request and putting it in the HTTP `Authorization` header with the auth-scheme `JWT`, under the auth-param `token`. Example (line breaks are for display purposes only):
+Authorization is carried out by generating a JWT token for each request and putting it in the HTTP `Authorization` header with the auth-scheme `JWT`, under the auth-param `token`. Example (_line breaks are for display purposes only_):
 
 ```
 Authorization: JWT token="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiO\
@@ -33,7 +33,9 @@ Use the `HS256` (HMAC-SHA256) algorithm. Example header:
 
 ### Secret
 
-Ask one of us for the secret.
+If you're running your own self-hosted instance of BadgeKit, the secret should be whatever you set as `MASTER_SECRET` in your environment configuration.
+
+If you're using the Mozilla hosted version of BadgeKit - get in touch with the team for the secret.
 
 ### Example in JavaScript
 ```js
@@ -60,7 +62,7 @@ var token = jws.sign({
 ## Purpose of Each Claim
 
 * **key**: To look up the secret used to sign the token.
-* **exp**: General protection against replay attacks: a short lived token has limited opportunity for re-use.
-* **method**: Protection from replay attacks against the same URL with a different method, e.g., converting a POST request into a DELETE request.
-* **path**: Protection from replay attacks with the same method but against a new URL, e.g, using the same token for a POST to `/systems/chicago` as the token for a POST to `/systems/new-york`.
+* **exp**: General protection against replay attacks - a short lived token has limited opportunity for re-use.
+* **method**: Protection from replay attacks against the same URL with a different method, e.g. converting a `POST` request into a `DELETE` request.
+* **path**: Protection from replay attacks with the same method but against a new URL, e.g using the same token for a `POST` to `/systems/chicago` as the token for a `POST` to `/systems/new-york`.
 * **body**: Protection from data tampering; ensures the data that the client intended to send is the data received.

docs/issuing.md

@@ -31,6 +31,10 @@ Issuing is the process of awarding a badge to a specific earner. In BadgeKit API
  * `POST /systems/:slug/badges/:slug/instances`
  * `POST /systems/:slug/issuers/:slug/badges/:slug/instances`
  * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances`
+* [Create Multiple Badge Instances](#create-multiple-badge-instances)
+ * `POST /systems/:slug/badges/:slug/instances/bulk`
+ * `POST /systems/:slug/issuers/:slug/badges/:slug/instances/bulk`
+ * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/bulk`
 * [Delete an Instance](#delete-an-instance)
  * `DELETE /systems/:slug/badges/:slug/instances/:email`
  * `DELETE /systems/:slug/issuers/:slug/badges/:slug/instances/:email`
@@ -274,6 +278,85 @@ The assertion URL represents the location of the badge assertion. A badge assert
   }
 ```
 
+## Create Multiple Badge Instances
+
+The API supports bulk issuing of badges. The endpoint allows a particular badge to be issued to multiple earner email addresses.
+
+### Expected request
+
+```
+POST /systems/:slug/badges/:slug/instances/bulk
+POST /systems/:slug/issuers/:slug/badges/:slug/instances/bulk
+POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/bulk
+```
+
+Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`.
+
+| Parameters             | Required        | Description              |
+|:-----------------------|-----------------|--------------------------|
+| **emails** | required | Array of email addresses for the earners the badge is being issued to. |
+
+### Expected response
+
+```
+HTTP/1.1 201 Created
+Content-Type: application/json
+```
+
+```json
+{
+  "status": "created",
+  "instances": [{
+      "slug": "abcdefghi123456789abcdefghi123456789",
+      "email": "[email protected]",
+      "expires": null,
+      "issuedOn": "2014-05-29T10:16:01.654Z",
+      "claimCode": "abcde12345",
+      "assertionUrl": "http://issuersite.com/public/assertions/abcdefghi123456789abcdefghi123456789",
+      "badge": null
+  },
+  ...
+  ]
+}
+```
+
+The bulk issuing route does not accept the claim code parameter. If the badge has already been issued to an email address in the passed array, it will not be issued again and the returned array will not contain a badge instance for that email. Similarly, if an email address was included twice in the array, only one instance will be created and returned.
+
+#### Response structure
+
+* status
+* instances `[ ]`
+ * 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": "..."
+      },
+      ...
+    ]
+  }
+```
+
 ## Delete an Instance
 
 Delete a badge instance within a system, issuer or program context.