Skip to content

Instantly share code, notes, and snippets.

Created May 13, 2014 10:06
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save bradwright/58cd2a1e4484f218ebee to your computer and use it in GitHub Desktop.
Save bradwright/58cd2a1e4484f218ebee to your computer and use it in GitHub Desktop.
GOV.UK versioning API


An append-only datastore with API to store all published versions of a document.

User needs

  • As a citizen, I need to see change history of a document so I can see how a policy or official document evolves over time (TRUST)
  • As someone whose job relies on historical versions (e.g a tax accountant, lawyer), I need to be able to see older versions of documents from specific points in time, so I can refer to them

Technical sketch

  • MongoDB datastore with a single collection:
  "change_note": "Updated due to x",
  "updated_at":  Date(),
  "base_path":   "/base-path-to-document",
  "document":    {}
  • Simple API:
    • GET /versions/base-path-to-document returns all versions sorted chronologically
    • POST /versions/base-path-to-document automatically adds a new version. Needs the following schema: {change_note: 'something changed', updated_at: Date(), document: {}}


  • Should we support major/minor versions here?
    • Could we implicitly support minor versions by making change_note optional?
  • Should we support 1.x style version numbers (related to above question about minor/major versions)
Copy link

alext commented May 13, 2014

Looks good. A couple of points:

Given this is append only, would created_at be a better name for the timestamp field?

Secondly, we would end up duplicating the base_path field at the top-level and within the document. I'm not sure that's actually a problem, but worth mentioning.

Copy link

heathd commented Jun 20, 2014

Have you considered whether we need to deal with slug/url changes? Although I agree that it should generally discouraged, I think if we design the underlying services around the fact, we will make those rare cases where slug changes are needed very difficult to handle.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment