# Filing-history links **URL:** \ **Category:** Uncategorized\ **Created:** [August 24, 2015, 4:34pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241 "2015-08-24T16:34:31Z")\ **Posts on this page:** 9\ **Page:** 1
**Author:** ![luke\_brooks](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/luke_brooks/32/1115_2.png) [@luke\_brooks](http://forum.companieshouse.gov.uk/u/luke_brooks)\ **Post date:** [August 24, 2015, 4:34pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/1 "2015-08-24T16:34:31Z")
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 ---
**Author:** ![csmith](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/csmith/32/8_2.png) [@csmith](http://forum.companieshouse.gov.uk/u/csmith)\ **Post date:** [August 25, 2015, 9:12am UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/2 "2015-08-25T09:12:31Z")
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](https://developer.companieshouse.gov.uk/document/docs/document/id/documentMetaData-resource.html)) ? Regards Chris ---
**Author:** ![luke\_brooks](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/luke_brooks/32/1115_2.png) [@luke\_brooks](http://forum.companieshouse.gov.uk/u/luke_brooks)\ **Post date:** [August 25, 2015, 11:37am UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/3 "2015-08-25T11:37:24Z")
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 ---
**Author:** ![csmith](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/csmith/32/8_2.png) [@csmith](http://forum.companieshouse.gov.uk/u/csmith)\ **Post date:** [August 28, 2015, 3:04pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/4 "2015-08-28T15:04:45Z")
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 ---
**Author:** ![luke\_brooks](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/luke_brooks/32/1115_2.png) [@luke\_brooks](http://forum.companieshouse.gov.uk/u/luke_brooks)\ **Post date:** [September 1, 2015, 8:40am UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/5 "2015-09-01T08:40:23Z")
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 ---
**Author:** ![csmith](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/csmith/32/8_2.png) [@csmith](http://forum.companieshouse.gov.uk/u/csmith)\ **Post date:** [September 7, 2015, 3:33pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/6 "2015-09-07T15:33:33Z")
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: > [@Help with Document API & Fetch a Document](http://forum.aws.chdev.org/t/help-with-document-api-fetch-a-document/255): > > Hi there, I was wondering if anyone has had any luck with the “Fetch a Document” within the Document API ([https://developer.companieshouse.gov.uk/document/docs/document/id/content/fetchDocument.html](https://developer.companieshouse.gov.uk/document/docs/document/id/content/fetchDocument.html)). The documentation is not very helpful: Authorization This header parameter contains the token\_type and the access\_token. See example Does anyone know what the token\_type and access\_token are? On the explore API section it asked for “id” (Which I know), “Authorization [sic]” (Which I don’t know… C ---
**Author:** ![csmith](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/csmith/32/8_2.png) [@csmith](http://forum.companieshouse.gov.uk/u/csmith)\ **Post date:** [September 7, 2015, 3:36pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/7 "2015-09-07T15:36:23Z")
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: > **[HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)** > > Hypermedia as the Engine of Application State (HATEOAS) is a component of the REST application architecture that distinguishes it from other network application architectures. > With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through hypermedia. A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia. > By contrast, clients and servers in ... ---
**Author:** ![ash](http://forum.companieshouse.gov.uk/letter_avatar_proxy/v4/letter/a/f19dbf/32.png) [@ash](http://forum.companieshouse.gov.uk/u/ash)\ **Post date:** [September 7, 2015, 4:23pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/8 "2015-09-07T16:23:49Z")
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](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. ---
**Author:** ![csmith](http://forum.companieshouse.gov.uk/user_avatar/forum.companieshouse.gov.uk/csmith/32/8_2.png) [@csmith](http://forum.companieshouse.gov.uk/u/csmith)\ **Post date:** [September 8, 2015, 12:04pm UTC](http://forum.companieshouse.gov.uk/t/filing-history-links/241/9 "2015-09-08T12:04:25Z")
Good point about the meta-data rate limit. We will take this under consideration 😉