GOV.UK versioning API

versioning-api.md

Summary

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: {}}

TODO

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

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.

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.