Filing-history links

Hello there, I’m still migrating the app to the beta version of the new API

Our current migration can sometimes spend about five seconds in calls for metadata currently.

Will all companies have ‘document_metadata’ links in the finished API?

Kind regards,
Luke

There are some company filing histories that are in the process of being updated with document information, which ultimately concludes with adding the metadata link to the finling history entries.

I’m not sure what you are saying about the “five seconds in calls for metadata”. Are you saying that the API calls take five seconds to complete? Is it the call to get the metadata (ie calling https://developer.companieshouse.gov.uk/document/docs/document/id/documentMetaData-resource.html) ?

Regards
Chris

It’s in calls for document urls based on a company’s company number. Would be nice if every ‘items’ element returned at /company/company_number/filing-history returned direct links for the document they pertain to. The calls as it stand are to the documents api for entries missing ‘document_metadata’ links,

on average it can be about 4 seconds for a typical company that’s lacking some links.

Kind regards, Luke

Can you give an example (perhaps an API call chain) for a request where there is missing meta_data link?

If there is a missing meta_data link on the filing history, then that document is not available. If you have a meta_data link, then calling it will return which document types are available. Currently we have just PDF, but shortly accounts filings will be available in both PDF and iXBLR/XBRL, if they were filed electronically. The filing history cannot know what document types are available, as that is a function of the document server, as type availability will be variable and change over time as new types are introduced.

We look forward to the example so we can see if we can help!

Regards
Chris

Hey Chris thanks for that, turns out I was being unobservant and hadn’t noticed that the link in the metadata field to document-api could also be used as the direct link to the document’s content by appending /content […]

Bit embarrassing but glad it’s resolved.

Cheers
Luke

Yes you can do that, but you would be taking an optimistic approach to the document being available in the format you want.

This is fine if you protect your client by having it expect and handle request failures. A metadata request will always succeed and tell you which document types are available (PDF, XBRL, iXBRL etc). If you’re always looking for a PDF, then your user journey doesn’t care about other formats, however, if you’re exposing a choice of documents to a user, then you need to drive that from the metadata request so that you’re user is informed as to what document types are available. Taking the optimistic approach, you could fire off a metadata request only if your request for a PDF, for example, fails…

More types will be added over time, and the API design transparently offers the new types to you (and your users), making it possible to create a client that does not need to know about the available types, and therefore be future proof.

There is another query with a similar outcome:

C

Also, if users of the API do want a direct link to the PDF document (making a big assumption here that a PDF render is always available), then the links: {} sub-document of the filing history item should contain a direct pdf-document link. If this is a common use-case, then we will look at making the change. Client side URL (re)construction should not be necessary:

We’re currently using an “optimistic” approach and assuming everything is available as a pdf. But I’m taking all this on board.

One problem I had, based on the assumption that the metadata request counts against the document api rate limit (can you confirm if this is the case or not?). If they do then any application that renders a filing history with document availability for a company with a long history is going to run into issues.

For something like British Airways (https://beta.companieshouse.gov.uk/company/01777777) you’re looking at over 1000 calls to the document api to verify the avaialbility of all documents as a PDF which takes an individual account well over the limit without even downloading a document.

If these calls don’t count then it isn’t an issue in terms of rate limits, but for long history it’s still a lot of roundtrips to the API. We can access and link directly to the PDF of 100 items from a filing history in a single call (if we operate under the optimistic pdf assumption) but to do the same and verify the documents are available as pdfs will take 101 calls.

Good point about the meta-data rate limit. We will take this under consideration :wink: