I am curious why there is the need to reinvent the wheel by creating yet another API when the XML Gateway which has been around for years, is mature and stable. If the intent is to creat a JSON API would it not have been better to simply map JSON request/response objects to the existing XML gateway API? This is something that could be achieved in weeks, not months, and would be relatively pain free.
I guess I am questioning the underlying business/technical drivers behind this new project, so could someone stick their neck out and elaborate please?
That is an interesting point, and perhaps one that others may have questioned themselves. So this seems a good opportunity to elaborate on why Companies House is moving in this direction, which is actually an industry wide shift, born out of consumer need.
The new Companies House API is not re-inventing the wheel, but brings Companies House’s digital platform up to current technological standards, thereby meeting the expectations of consumers who come to us for data. And there are other reasons to do this, most of which can be applied to any organisation or service:
Customer need. New users of our XML Gateway frequently request a modern RESTful API instead of a rather dated XML RPC approach.
Simplicity of use. Clients simply consume and modify information, which offers a more natural and lower barrier to entry to the end customer. It’s all about the data. The concept of a “form” therefore does not feature in a RESTful API. Our API will make sure the Companies House public register is correctly affected.
To successfully deliver open and free data, the adoption of schema-less RESTfull API’s, following a HATEOAS - Wikipedia approach, simplifies clients and the consumption, and importantly, the discovery of information.
Versioning. With XML, every change is a breaking change, however insignificant, and a source of continuous pain for service provider and consumer alike. Adopting JSON, with it’s loose schema association, increases the agility and speed with which the API can change to user need.
Ease of integration. JSON is simple to consume and understand. It maps directly to the basic data types of most languages.
Lastly, from our own experience and customer feedback, there are many issues with the existing XML Gateway documents, in the way they model data, their granularity, and their ability to represent future legislative change. Fundamentally though, these documents represent operations and not the actual data, so a like-for-like XML to JSON map is simply not possible, since it’s not so much the representation that is changing, but what is being represented.
As an aid to migration, we are looking to see if we can produce an entity-to-entity map document.
Hope that helps clarify the shift. Don’t hesitate to come back if you need more, I’ve got plenty of helpful links I could send you.
Thanks for the detailed reply. It makes a lot more sense now that I have detailed insight into the project goals/objectives.
This is a slight deviation from the original question but related in a roundabout way I guess, so apologies in advance! Are you in a position to elaborate on the what the future holds for the XML Gateway, especially for those who have an investment in that API? Specifically, will it continue to be supported in parallel with the JSON API and are there any plans afoot to remove access charges for docs, etc.? In other words should businesses who have a stake in the XML Gateway just sit tight, or will we be left high and dry if we don’t migrate to the JSON API?
We have always stated that the new JSON API will be a replacement for the XML Gateway and at some point in the future we will be deprecating the service. There has been no decision taken on the timescales for the closure but notice and support will be given to customers.
However, we are currently developing the XML Gateway to cater for the upcoming legal changes related to the Small Business, Enterprise and Employment Act (SBEE) some of which are planned to be implemented in October 2016. Therefore the service will be operating for a period of time beyond this date.