mozilla/badgekit-api — pull request #91 by SueSmith (2014-05-30 12:33:33+00:00)
Title: Doc updates

I've gone through the endpoints and updated the docs (with a bit of guesswork in some cases..). Added a few pages, linked them to one another and put a README in the docs directory.

A few things I wanted to check:

* Should these endpoints be in there?
* `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`
* I've removed the `evidence` endpoints - am I right in thinking it's just handled via the `applications` endpoints?
* I found that the `systems` endpoints didn't include the `description` field..? The `programs` array seems to be empty on the same endpoints. (I've included these in the docs so they'll need removed if that's wrong.)
* I've listed `type` as required for badges, is this correct? (See issue #90).
* I wasn't sure what the purpose of the `email` field is with claim codes..?
* When I attempted to create a duplicate claim code I didn't receive an error message - is this right? (I've included a duplicate entry error message so will need to change it if it shouldn't be returned..)
* When deleting a badge instance, the response I got didn't include a `status` field..? Unlike other delete endpoints where `deleted` status is returned.. (Haven't included in docs so will need to add if it should be there.)
* When I tried to create a badge instance including an invalid claim code I didn't get an error returned but the API did seem to crash..? (If this should have a particular error message I'll need to add it to the docs.)
* When creating a badge instance, I'm getting a response with a null `badge` in it - does the badge get returned depending on the parameters you include when creating the instance?
* I'm a bit unclear on these `applications` fields (could do with fleshing out their explanations):
* `assignedTo` - is this the email address of the reviewer?
* `assignedExpiration` - is this a date by which the application should be reviewed or a date for the badge to expire?

Hope all that makes sense...!

Closes #89