Document the Draw My Life Drawings API

[CathMollie]

🌵 STATUS: Please refer to comment thread for progress, this is done and needs review. 🌵

Blocks: #161

What

Eventually, clients such as external campaign tools and hackathon apps should be able to query our drawings API.

We need to finalize and document our initial single-entity and collection API endpoints for drawings. This has already been started over at http://docs.drawmylife.apiary.io/# but it's worth a revisit to ensure it's up-to-date and accurate. If you have a background in API design, any suggestions welcome!

NB: API documentation is as important as good customer service. We want any developer to be able to browse our API documentation and get started quickly. Make descriptions explicit, succinct and clear, and provide accurate example requests and responses. You might want to find some good examples of public API documentation out there and follow suit!

How

We're using Apiary to prototype and document our API design. See http://docs.drawmylife.apiary.io/# - ask @krissy for access!

We need to revisit and update these since the initial draft.

Considerations

We're building a hypermedia REST API using the JSON-HAL spec.

You can see what we currently expose by logging into the admin tool and then accessing an endpoint like /drawings/1.hal (singular) or /drawings.hal (collections). This is not necessarily correct but should give guidance of how we're currently exposing data.

We want to check what we're exposing is in line with what we're collecting, and that we only expose image URLs of drawings that have consent explicitly given.

[krissy]

The API docs have been edited to reflect our current fields and structure in a way that clearly separates drawing vs artist data.

You can view the docs for each endpoint here:

Drawing (single entity): http://docs.drawmylife.apiary.io/#reference/drawings/drawing/retrieve-a-drawing

Drawing (collection): http://docs.drawmylife.apiary.io/#reference/drawings/drawing-collection/list-all-drawings

It would be great to get these reviewed by someone with experience in hypermedia API design, specifically JSON HAL standards.