Currently to generate a complete description of File History item we have to look-up the hyphenated description provided in the API response and then iterate through the key/value pairs in description_values to construct the the actual description.
However these items are not typed in any way and when the value is a date it is unformatted.
This means that when the procedure of generating a description is automated we have no way of knowing when a value is a date, so we can format it accordingly.
At present I am checking if the key contains the literal string “date” and then attempting to format the value if it does, but returning the unformatted value if this throws an exception… this is very bad practice on a number of levels, but I can’t think of any other way to deal with this.
The beta search facility must be doing this somehow as dates are formatted in the item descriptions there.
We’ve recently spotted this irregularity (when working up the latest release of search). Our web service is doing as you have implemented and detecting the member ending in _date. This is bad practice and not sustainable, so we will want to address this.
Unofficially, and off the top of my head, I see two solutions:
Do the same we have with search and prefix the expansion in the enumeration with a type, such as {date:charge_creation_date} (I only imagine these being necessary for dates).
Change the API response so that we have description_values: {} and description_dates: {}
works if you’re always using the enum expansions to form descriptions. 2) works if you’re purely dealing with data, but is more complicated.
Like I said, we’ve implemented 1. for search, and is really easy to do the expansion/population. Once you’ve coded it, you use it wherever needed - and we want to use the same approach across the entire API suite.
Localisation is important, as our data is consumed globally.
For 2), Have a look at search (and the search_descriptions.yml api-enumeration text). Does this help you?
Your _date method has issues because it doesn’t detect cases where it’s just “date”, you can see this in the beta search where resolutions and associated filings are dated. On the fourth item the bolded resolution text has the date unformated because of this:
I’ll switch my own stuff to check for just “date” or “_date” as that’s probably safer than looking for date anywhere in the string. I think either of the other solutions would be fine though.
I’ve encountered a couple of other formatting issues, but I’ll stick anything else in it’s own thread to avoid confusion!
Data sets such as the filing history are difficult to expose beneath a consistent API, due to the changes the data has gone through over time, and the different ways data has been captured over the years. It’s a major headache! This means intelligently remodelling the data, which is difficult, so we’ll do it behind the API and make it easy for clients.
We’ll need to iterate to get this right, but we firmly believe that getting it out there early and iterating often is the way forward for this beta (especially now we have measures in place to notify you of changes before they happen…).
I’ve spotted a few other things in the filing history documentation today, so this API will be revisited soon.
.