search

DemocracyClub / EveryElection

:ballot_box_with_check: For recording every election in the UK
https://elections.democracyclub.org.uk/
BSD 3-Clause "New" or "Revised" License
11 stars 14 forks source link

Produce API documentation #421

Open symroe opened 6 years ago

symroe commented 6 years ago

When reviewing https://github.com/DemocracyClub/yournextrepresentative/pull/672 I realised that we don't really expose the API filters at all at the moment, and we don't enumerate the (soon to be merged) status objects.

API consumers that haven't talked to us or read the code wouldn't know what they can filter on.

As a start, I think we should use django-filter to expose the stuff we currently do in the get methods, and provide an endpoint for the various election statuses we assign to elections.

chris48s commented 6 years ago

Totally agree, but I'd like to expand the scope of this slightly to "produce API documentation" as there's a bunch of other stuff (as well as the filters) that is really non-obvious.

For example, it isn't obvious from here: https://elections.democracyclub.org.uk/api/organisations/local-authority/ADU/1974-04-01.json that you can also call this: https://elections.democracyclub.org.uk/api/organisations/local-authority/ADU/1974-04-01/geo.json but you can.

Similarly with https://elections.democracyclub.org.uk/api/elections/local.cheshire-east.alderley-edge.2011-05-05.json and https://elections.democracyclub.org.uk/api/elections/local.cheshire-east.alderley-edge.2011-05-05/geo.json

The concept of cancelled elections (which we haven't introduced yet), election meta-data (e.g: for stuff like voter id pilots), election explainers etc are also going to be really non-obvious because they're so rarely populated.

General schema docs (what do all these JSON keys mean, what are the possible values that might appear in them, etc). All essential for anyone wanting to consume this data and we have none of this. i.e: ideally every field should have some kind of reference like:

field type description
election_subtype object, nullable Some election types specify an optional subtype:

  • National Assembly for Wales
    • Constituencies
    • Regions
  • Scottish parliament
    • Constituencies
    • Regions
  • Greater London Assembly
    • Constituencies
    • Additional

Also related to this in the back of my mind is that one of the more recent DRF releases introduced some native documentation tooling which I'd like to try out when we tackle this.

Documenting the filters is one step on the path to that though :)

symroe commented 6 years ago

I think DRF are moving towards OpenAPI, so we should investigate how to play nicely with that.

chris48s commented 6 years ago

I've not really looked into it in any more detail than seeing this is now provided as part of the core DRF package:

https://www.django-rest-framework.org/community/3.6-announcement/#interactive-api-documentation

and making a mental note to investigate in more detail when we get to this, but I assume it is OpenAPI spec based under the hood.