API versioning behaviour

Documentation Issues
1

Hi,

I’m working on integrating the Companies House Public Data API for an application.

At the moment I understand the API versioning documentation to be one of:

  1. Proposed but never implemented.
  2. Implemented but the documentation is out of sync and does not reflect reality.

This is from:

  1. Following the documentation about versioning but not seeing the behaviour as described. E.g. there’s content type returned for any resources that I use.
  2. Forum posts proposing the versioning mechanism, noting the lack of documentation about resource versions and other people asking the same question
  3. Looking at the node-sdk’s API client there is no reference to any versioning. E.g. the API client specifies an Accept header but it defaults to application/json and the tests reflect that this is primarily to support application/merge-patch+json argument.

Is it possible to:

  1. Have someone clarify the current implementation, or absence, of versioning? Being against the latest version of an API by default introduces a level of risk whereas being against a specified version would be preferable. Either way any insight on this would be very useful.
  2. Have the documentation about versioning either be updated or deleted? I’ve also emailed support trying to find out about this and repeatedly received links to the versioning page (which I believe to be out of date).

Very happy if anything posted here is wrong and for it to be clarified.
Thanks in advance

2

Not from Companies House but you certainly seem to have carried out all the research we have (e.g. read docs, search forum, occasionally check the XML API for parallels and maybe even the source code).

Hopefully Companies House can confirm (and if any change is scheduled) but I think the situation is closer to “1. Proposed but never (fully) implemented.”