Merge pull request #117 from mozilla/doc-tidy

Doc updates/ tidying

README.md

@@ -10,19 +10,21 @@ __The BadgeKit Web app links to the API to create an admin user interface for cr
 
 The BadgeKit API provides a series of endpoints through which your sites can interact with data for badges, earner applications and issuer organization admin. Below are some examples of calls you can make to the API.
 
-Retrieve/ Update/ Add new:
-* badges
-* earner applications for badges
-* application reviews
-* _issuers within a system_
-* _programs within an issuer_
-* _badge/ application data for a particular issuers/ programs_.
+* Retrieve badges
+* Submit earner applications for badges
+* Submit application reviews
+* Issue badges
+* Generate claim codes for a badge
+* Update badge data
+* Manage badges within system, issuer and program admin levels
 
 __Using issuer and program admin levels is entirely optional - you can simply configure BadgeKit to group all of your badge and application data within a single system.__
 
+The repo [docs](docs) list all of the available endpoints provided by the API, together with examples of request and response data.
+
 When you make a request, the API returns JSON data. You can then present the returned data within your own site interface.
 
-In addition to the series of calls you can make to interact with data, the API also provides webhooks for badging events (such as a badge being issued or an earner application being reviewed). By configuring a URL to receive notification of these events, you can build your own custom responses, for example informing an earner that their badge application was successful.
+In addition to the series of calls you can make to interact with data, the API also provides [webhooks](docs/webhooks.md) for badging events (such as a badge being issued or an earner application being reviewed). By configuring a URL to receive notification of these events, you can build your own custom responses, for example informing an earner that their badge application was successful.
 
 To get started accessing the API in your own sites, see [Using BadgeKit API](https://github.com/mozilla/badgekit-api/wiki/Using-BadgeKit-API).
 
@@ -34,16 +36,16 @@ API calls should be signed with a JWT token generated using the secret for your
 
 To install the BadgeKit API: 
 * clone the repo
-* set up a database
-* set your environment configs.
+* set your environment configs
+* set up your database
 
-You can use the `schema.sql` file in the root directory to create your database. You also need to add an entry in the `system` table, providing an initial slug and system name for a badge issuing system. See the [wiki](https://github.com/mozilla/badgekit-api/wiki) for more details and the [Self-Hosting guide](https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-Self-Hosting-Guide) if you plan on building your own instance of the BadgeKit Web app as well as the API.
+You can use `bin/db-migrate up` from the root directory to create (or migrate) your database. You also need to add an entry in the `systems` table, providing an initial slug, system name and URL (optionally also description, email and image) for a badge issuing system. See the [wiki](https://github.com/mozilla/badgekit-api/wiki) for more details and the [Self-Hosting guide](https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-Self-Hosting-Guide), particularly if you plan on building your own instance of the BadgeKit Web app as well as the API.
 
 ## Environment Configuration
 
-The BadgeKit API currently uses the following configuration details:
+BadgeKit API currently uses the following configuration details:
 
-* `NODE_ENV`: Set to `production` for production environments. If you want to run the test suite, set this to `test`. **DO NOT SET THIS TO `test` ON PRODUCTION MACHINES, BAD THINGS WILL HAPPEN** - mainly authentication will be inactive and you run the risk of accidentally dropping your database.
+* `NODE_ENV`: Set to `production` for production environments. If you want to run the test suite or to try out the API endpoints without JWT authorization, set this to `test`. **DO NOT SET THIS TO `test` ON PRODUCTION MACHINES, BAD THINGS WILL HAPPEN** - _authentication will be inactive and you run the risk of accidentally dropping your database_.
 * `DB_HOST`: Defaults to `localhost`.
 * `DB_NAME`: Name of the database to store BadgeKit data.
 * `DB_USER`: User who has full access to the `DB_NAME` table.

docs/README.md

@@ -16,7 +16,7 @@ The BadgeKit API docs include the information you need to get started using the
 * [Webhooks](webhooks.md)
 * [Authorization](authorization.md)
 
-You can interact with badge and application data managed by the API using the endpoints. The data you send to the API endpoints needs to be signed for authentication, and the data you receive from the API (in responses and webhook messages) is signed before it is sent. To detect badging events carried out through the API, such as badges being issued and badge applications being reviewed, you can configure a webhook URL to which BadgeKit API will send data.
+You can interact with badge and application data managed by the API using the endpoints. The data you send to the API endpoints needs to be signed for authentication, and the data you receive from the API (in responses and webhook messages) is signed before it is sent. To detect badging events carried out through the API, such as badges being issued/ revoked and badge applications being reviewed, you can configure a webhook URL to which BadgeKit API will send data.
 
 The API docs provide a reference for the endpoints and webhooks. You will also find detailed guides to carrying out common processes, including the assessment flow, together with sample code excerpts, in the [BadgeKit API wiki](https://github.com/mozilla/badgekit-api/wiki):
 

docs/api-endpoints.md

@@ -38,6 +38,7 @@ See the following overview of the available BadgeKit API endpoints - browse to t
     * **DELETE** /systems/:slug/badges/:slug
     * **DELETE** /systems/:slug/issuers/:slug/badges/:slug
     * **DELETE** /systems/:slug/issuers/:slug/programs/:slug/badges/:slug
+    * **GET** /public/badges
   * [Claim Codes](claim-codes.md)
     * **GET** /systems/:slug/codes/:code
     * **GET** /systems/:slug/issuers/:slug/codes/:code
@@ -118,11 +119,3 @@ See the following overview of the available BadgeKit API endpoints - browse to t
     * **DELETE** /systems/:slug/milestones/:milestoneId
 
 See also [authorization](authorization.md) and [webhooks](webhooks.md).
-
-<!--
-* **GET** /public/systems/:slug 
-* **GET** /public/systems/:slug/issuers/:slug
-* **GET** /public/systems/:slug/issuers/:slug/programs/:slug 
-* **GET** /public/assertions/:slug
-* **GET** /public/images/:imageId
--->

docs/assessment.md

@@ -12,8 +12,8 @@ Assessment therefore involves two objects in BadgeKit API: applications and revi
 | `slug` | __string__ |
 | `learner` | __email address__ - _earner email_ |
 | `created` | __timestamp__ |
-| `assignedTo` | __string__ - _email login for assigned reviewer_ |
-| `assignedExpiration` | __timestamp__ |
+| `assignedTo` | __string__ - _email address for assigned reviewer_ |
+| `assignedExpiration` | __timestamp__ - _expiry date for assigned reviewer to complete review, after which another reviewer can be assigned_ |
 | `badge` | [badge](badges.md) - _badge applied for_ |
 | `processed` | __timestamp__ - _e.g. set when review is submitted or when badge instance is created_ |
 | `evidence` | __array__ - _each evidence item can include: `url`, `mediaType` (which can be `image` or `link`) and `reflection` (which is a string)_ |
@@ -27,7 +27,6 @@ Assessment therefore involves two objects in BadgeKit API: applications and revi
 | `author` | __email address__ - _reviewer email_ |
 | `comment` | __string__ - _applicant feedback_ |
 | `reviewItems` | __array__ - _one for each criteria item in the badge; each reviewItem can include: `criterionId`, `satisfied` status and `comment`_ |
-| `approved` | __boolean__ - _indicates success of application_ |
 
 ## Endpoints
 
@@ -90,6 +89,13 @@ GET /systems/:slug/issuers/:slug/badges/:slug/applications
 GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications
 ```
 
+#### Available request parameters
+
+* **`page`:** - page of results to return
+* **`count`:** - count of results to return per page
+
+e.g. `/systems/<slug>/applications?count=2&page=1`
+
 ### Expected response
 
 ```
@@ -130,10 +136,19 @@ Content-Type: application/json
             ]
         },
         ...
-    ]
+    ],
+    "pageData": {
+        "page": 1,
+        "count": 2,
+        "total": 4
+    }
 }
 ```
 
+Applications are returned in order sorted by created date.
+
+__`pageData` is returned when pagination parameters are used.__
+
 #### Response structure
 
 * applications `[ ]`
@@ -261,7 +276,7 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded`
 | **learner** | required | The email address for the earner applying. |
 | **evidence** | optional | Array including evidence items - each item can include `reflection`, `mediaType` and `url`. |
 | **assignedTo** | optional | Email of reviewer application is assigned to. |
-| **assignedExpiration** | optional | Expiry date. |
+| **assignedExpiration** | optional | Expiry date for assigned reviewer to complete review. |
 
 ### Expected response
 
@@ -359,7 +374,7 @@ Requests can be sent as `application/json`, `application/x-www-form-urlencoded`
 | **learner** | The email address for the earner applying. |
 | **evidence** | Array including evidence items - each item can include `reflection`, `mediaType` and `url`. |
 | **assignedTo** | Email of reviewer application is assigned to. |
-| **assignedExpiration** | Expiry date. |
+| **assignedExpiration** | Expiry date for assigned reviewer to complete review. |
 | **processed** | Timestamp indicating application has been processed. |
 
 You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged.
@@ -507,6 +522,13 @@ GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews
 GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews
 ```
 
+#### Available request parameters
+
+* **`page`:** - page of results to return
+* **`count`:** - count of results to return per page
+
+e.g. `/systems/<slug>/badges/<slug>/applications/<slug>/reviews?count=2&page=1`
+
 ### Expected response
 
 ```
@@ -532,10 +554,17 @@ Content-Type: application/json
             ]
         },
         ...
-    ]
+    ],
+    "pageData": {
+        "page": 1,
+        "count": 2,
+        "total": 4
+    }
 }
 ```
 
+_`pageData` is returned when pagination parameters are used._
+
 #### Response structure
 
 * reviews `[ ]`