Doc updates

[SueSmith]

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 Badge field 'type' is not 'required', but the request fails if it's not supplied #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...!

P.S. You can ignore all the commit comments, I just included them to remind me to ask the above questions...

Closes #89

[SueSmith]

Commit comments can all be ignored, all questions are summarised in comment at top of PR..

[cmcavoy]

• 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

No, those should be removed

• I've removed the evidence endpoints - am I right in thinking it's just handled via the applications endpoints?

Yes, that's correct.

• 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.)

Because the system is ultimately the front-end site, I don't think it's a big deal if description isn't in there. That said, opened a ticket #98.

• I've listed type as required for badges, is this correct? (See issue Badge field 'type' is not 'required', but the request fails if it's not supplied #90).

For now, yes.

• I wasn't sure what the purpose of the email field is with claim codes..?

Once the claim code is claimed, the email address is stored. At least, that's how it worked in OpenBadger. Might be a relic from that era. Will investigate in #99.

• 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..)

No, that's a bug. Duplicate claim codes should throw an error. Tracked in #100.

• 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.)

Believe that's also a bug. #101

• 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.)

Tracking this as a bug #102

• 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?

Tracking this in #103, but need more information...

• 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?

assignedTo is the email address of the reviewer, assignedExpiration is when the assignment expires and another reviewer can be assigned. It prevents an application from getting stuck in limbo.

Thanks @SueSmith this is fantastic work! I'm going to merge this as is.

[SueSmith]

Thanks @cmcavoy - am always a bit wary of creating issues in case I'm just not understanding things.. Will do a new PR for any remaining bits of tidying up.