Agreed. The issues here are:
- The documentation doesn't match what the API produces.
- The documentation isn't clear about what circumstances produce specific "error" responses.
Some examples (using cUrl - the -I flag just returns the header instead of the response body to show that):
curl -u{myAPIKEY}: "https://api.companieshouse.gov.uk/company/00229606/charges"
... returns the charge list, since that exists for the company.
curl -u{myAPIKEY}: -I "https://api.companieshouse.gov.uk/company/05003861/charges"
...returns "HTTP/1.1 404 Not Found" in the header since there are no charges recorded.
(Just search on Beta to find companies with / without charges).
Using a completely non-existent company number:
curl -u{myAPIKEY}: -I "https://api.companieshouse.gov.uk/company/99990303/charges"
...returns "HTTP/1.1 404 Not Found".
Ignoring the docs for the moment (which mention HTTP returns of 200, 400 and 401) the API behaviour appears to be:
- If there are charges, you get code 200 and a chargelist resource.
- If the company doesn't have charges or the company number doesn't exist in the API dataset, you get a 404.
Obviously you could test to see if the company has charges by requesting the company profile first and checking the "has_charges" member. (Note this doesn't mean "has active charges" but "has / had charges, fullfilled or not").
Someone from CH could maybe make a note on the documentation that it may differ from the API in numerous areas, but if they were going to do that I guess they could just go ahead and update the docs...
Veering away from original question - across the API queries are inconsistent in their behaviour when data is missing / query "doesn't apply":
1) Company profile request where company number doesn't exist or company was removed from CH API dataset:
curl -u{myAPI KEY}: "https://api.companieshouse.gov.uk/company/05207708"
{"errors":
[ { "type" : "ch:service", "error" : "company-profile-not-found" } ]
}
2) Filing history may return a blank data set (with status "filing history available"!)
curl -u{myAPI KEY}: "https://api.companieshouse.gov.uk/company/05207708/filing-history"
{
"start_index" : 0, "filing_history_status" : "filing-history-available",
"items" : [ ], "total_count" : 0, "items_per_page" : 25
}
3) Charges (as you point out) give 404 if there is no data.
4) Insolvency history doesn't seem to give 404 but instead you may get a "null" response if there isn't one e.g.:
curl -u{myAPI KEY}: "https://api.companieshouse.gov.uk/company/05003861/insolvency"
null
5) PSCs return an error object:
curl -u{myAPI KEY}: "https://api.companieshouse.gov.uk/company/03888792/persons-with-significant-control"
{ "errors" : [ { "type" : "ch:service", "error" : "company-psc-not-found" } ] }
6) Registers (I have never used this or found any example with data here, but presumably someone does):
curl -u{myAPIKEY}: -I "https://api.companieshouse.gov.uk/company/05003861/registers"
HTTP/1.1 404 Not Found
...
