Trouble retrieving Document MetaData/Documents, a.k.a. frustrated at this API

1

I’ve used quite a few RESTful API’s over recent years, but never before have I encountered one that is as frustrating this!

I have a simple task: retrieve the filing history list for a company, then retrieve a document.

Simple right? Wrong!

Steps using the built-in website test tools:

  1. https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/getFilingHistoryList.html#here

I enter the company number I am interested in (01777777), items_per_page=100, and select my API key. Click ‘Try it Out’, works fine.

  1. https://developer.companieshouse.gov.uk/document/docs/document/id/fetchDocumentMeta.html#here

I enter the first ‘document_metadata’ URL returned which is https://document-api.companieshouse.gov.uk/document/Bn6EK_4buGwtLlVIFJO3OZcG2p9rj0w4-RwbtV8HR5s, then it asks for Authorisation.

The example on the page lists Authorisation as: Basic bXlfYXBpX2tleTo=

So on that note, ‘Basic’ is the token_type, but where do I get the access_token from??? When I try and enter my api key here, I get an error every single time:

0 error

Failure while contacting API. Some possible causes are connection problems or cross-origin resource sharing protection. Please check javascript domains registered against APIKey / OAuth2 registration.

If access_token was clickable I’d be able to follow it to a definition like any sane person would do, but no, that makes too much sense.

Apologies about the tone of this but I am incredibly frustrated at what should be a very simple task…

Kind Regards,
Ian Havelock

2

The access_token is your key followed by a colon (essentially key:password where there is no password), so the entire thing is

Basic yourAPIkey:

This is hinted at here and there, but it’s really not clear in the documentation and it’s (the colon) is still explicitly absent in the examples.

That said I have never been able to get any of the website tools for the document API to work and have only ever got the same resource sharing error you’ve pasted here. Have they ever worked for anyone?

3

Both,

Unfortunately the “try it out” function on the developer site for document metadata and document retrievals is broken, and needs to be resolved. Once fixed you will not be required to enter the authorization field as this is provided by the API key selected.

Apologies for the error on this page and will look to resolve as soon as possible.

With regards to retrieving documents and authorisation the attached post maybe of interest.

Apologies for the frustration.

Thanks,

@mfairhurst

4

Is the ‘try it out’ function on the developer site for document metadata and document retrievals still broken? it seems to still behave as described above on 9th March 2016.

5

@derek_holtham,

The issue is still on the backlog and has yet to be resolved. Apologies this is taking so long to resolve but we have a number of higher priority fixes and features we are working through. Rest assured it’s not been forgotten.

Thanks,

@mfairhurst

6

Thanks very much for confirming what I suspected, Mark. In the interim, though, could someone not mark the pages that don’t work, so people don’t waste time thinking they are doing something wrong?

2 Likes
7

I believe the test thing on the document page is still broken.

8

I would assume that. I just found this thread after 1/2 day trying different approaches for testing the document-API. When is this issue going to be looked into, realistically?

9

Could someone please confirm whether I can retrieve documents using the Fetch Document API functionality. I am aware that the test functionality in the website is broken.

10

Second the above question. Whatever I try while fetching a document using Documents API, all I get is status code 500. Maybe the documentation was not updated and we need to do a different request? Please help with this.

11

@rhariharan Yes, it does work as we use this API all the time.

I’ll just go with the most likely causes @reybravin - if you’ve got more detailed info post it. This issue mostly appears due to the way people (or rather - the framework / library / REST software they’re using) send the API key.

If you go through the authorization docs step-by-step (ideally using something really simple for debugging like e.g. cUrl) it should be clear. There were still some issues with other parts of the documentation last time I looked (e.g. the “test” facility being broken for one) but this part worked for me.

For an example of someone fixing this work through the information in the following thread (ignore that they’re using Postman). Hopefully that’ll also fix things for you:

http://forum.aws.chdev.org/t/document-metadata-500-error/1909/5

I can’t remember if the following gives a 500 - think not - but another source of trouble here is if you request the CH endpoint:

http://document-api.companieshouse.gov.uk/document/{long document ID code}/content

…and (when you check) the error is actually coming from Amazon. This may occur since CH actually send you a redirect to Amazon (who hold the data) and at that point if you send them your API key and http basic header they’ll get confused. See the following thread:

http://forum.aws.chdev.org/t/cant-access-documents-from-amazons3-server/1871/2

Detail about this 500 error.
Aside from not expecting a 500 error for a password issue the stumbling blocks seem to be:

“API key” is actually the user-ID part of the http basic authorization and there is no password part. So the “username and password” you send which http basic wants like this:

username:password

…is actually:

MY_API_KEY:

The other trap is if you’re building the http header yourself (e.g. not when using cUrl, many libraries etc.) you need to encode the whole “username:password” using Base64.

Chris