One of my big concerns with Helix is going to be the maintainability of the applications on our end. With Kraken, there have been countless times where an endpoint would roll out, but the response structure could change without warning. It’s almost as if updates were pushed out without proper QA/QC, hoping that whatever was pushed worked and met everyone’s needs. And to make matters worse, the changes would go undocumented for quite some time, often until they were pointed out by us. I know one of the goals with Helix was to avoid situations like these, but there have been a couple cases where this still occurred.
In my specific use case, I’m building a general use library for all of Helix, and more. I’m not looking for a specific set of information within the responses, but the entire responses themselves. When data structures can suddenly change without warning, this makes maintaining my library an absolute nightmare. Usually I only find out during my own testing, or through other people’s bug reports. This can, and has, resulted in situations where I thought I finished implementing an endpoint, to only realize that I’ve been “ignoring” data for quite some time.
Twitch has been getting better at notifying what changes, and where, but reporting these changes is usually very slow. Take, for example, the recent msg-id=giftsub tag with IRC (I know it’s not the API but the concept is the same). This tag was rolled out publicly weeks before there was any mention of it in the documentation.
I would love if there was automated way to check what the response structure should be, but also the query parameters used to make the requests. Currently, the only way to test the response right now is to manually hammer each endpoint and compare the content of the response vs. what was previously returned. This could be automated to an extent on our side, but it shouldn’t be that involved to maintain our applications so that they stay up to date at all times.
A solution along the lines of what was discussed in this thread would be an amazing thing to have access to, automated documentation from the source level. This was we know exactly what we’re getting into. An Open API specification for Helix.
TLDR
An Open API specification for Helix would be amazing.