V5 API does not conform to documents

[khalilsherif]

I have been working a bit with the v5 API and what I have found is that the documents does not accurately reflect the API.

Example:

 curl -i -H 'Accept: application/vnd.twitchtv.v5+json' -H 'Client-ID: MY-CLIENT-ID' 'https://api.twitch.tv/kraken'

will yield the following headers:

HTTP/1.1 200 OK
Date: Sat, 31 Dec 2016 18:55:18 GMT
Content-Type: application/json
Content-Length: 46
Connection: keep-alive
Server: nginx
Access-Control-Allow-Headers: Accept, Authorization, Client-Id, Twitch-Api-Token, X-Forwarded-Proto, X-Requested-With, X-Csrf-Token, Content-Type
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 0
Twitch-Trace-Id: REMOVED
Front-End-Https: on

However, in the documents located at

https://dev.twitch.tv/docs/v5/guides/using-the-twitch-api/

under API Versions and Mime Types

it clearly states there is supposed to be an x-api-version header.

The only reason I have come by this is that in the overview located at

Twitch Developer Documentation

It specifies that all _link objects have been removed, however doing a request

curl -i -H 'Accept: application/vnd.twitchtv.v5+json' -H 'Client-ID: MY-CLIENT-ID' 'https://api.twitch.tv/kraken/users/20037/follows/channels`

WILL yield the x-api-version header, however will still return _link objects.

[Six]

It sounds like you are sending requests to v3 and not v5, I had a similar issue at first. When I set the default accept header to v5, I was still attempting to send requests to v3. The way I got around this was by specifying the api version within the actual request itself as a query parameter and then everything returned as expected.

that being said, I still noticed some discrepancies between the api documentation and what was returned. For example, when requesting a page of channel feed posts, it says there should be a _total object returned, but when going into the actual returned content, no such object existed. Instead, there was a _disabled object.

[DallasNChains]

Thanks for the heads up, @khalilsherif! I’ll follow up on the x-api-version header and on that erroneous _links object.

@Six: That channel feed endpoint has changed since we shipped the docs apparently. Thanks for letting me know! I’m following up with the team about that. I can’t find the disabled object though. I see a _disabled field alongside the _cursor field, _topic field, and posts array. Do you have a JSON response you can share?

[khalilsherif]

Thank you @DallasNChains, its great to see staff take interest in developer input. Something quite a few services lack. The responsiveness of the API so far has been great and aside from minor discrepancies as previously mentioned, it is a nice improvement to previous versions.

[Six]

@DallasNChains This is the content from the response I get when I request a page of posts from my channel.

I’m sure we were talking about the _disabled at the top, I just forgot the underscore.

Also, there is one more strange thing that I noticed when requesting paged lists of the channel feed posts. Whenever I make a request, it seems like any posts that were deleted are also attempted to be included in the request but are ultimately left out in the response. Take the attached photo above. That request should have returned all 8 posts on my channel feed, but instead it only returned one. The other seven posts were all ones that I created and deleted while testing other endpoints. However, If I follow the cursor until it is empty I will successfully get all posts on my feed.

[DallasNChains]

@khalilsherif I’ve filed the header and _links issues as bugs with the API team.

@Six I confirmed that the channel feed data model was updated the day after I shipped docs. Go figure. I updated the responses. I don’t see the same cursor issue as you. Curious if that’s still happening. I’ve had a ton of created and deleted posts while writing the docs.

[Six]

@DallasNChains I just tried again and got the same results with not all posts showing up

[DallasNChains]

Interesting. I would expect deleted posts to not be in the result set, but I wouldn’t expect the cursor to page over them. I’ll ask the team that owns this API of that is expected. There is a deleted field, so I wonder if the cursor doesn’t take that into account.

[Six]

Hm, could be. Either way, thanks!

[Six]

@DallasNChains I figured I would just keep replying here instead of just making a new thread every time.

1. I found something that is a little misleading. The teams/{team} endpoint nests a list of users but really returns a list of channel objects. I know it’s wicked nit-picky and i know it does indeed conform to the documentation, but this is a little misleading, something that I didn’t pick up on until refactoring.

2. Also, the documentation users/{user_id}/follows/channels endpoint does not have a _links field but when a request is sent, there is a _links field returned in the blob in several locations:

So on further inspection, it looks like I somehow got a v3 response even though I specified v5 both in the header and in the actual request itself, somehow. Here are the parameters and headers on my request:

[khalilsherif]

I wouldn’t mind that this thread becomes a sticky or anything It helps towards my project, and will hopefully help other devs as well. Thank you for submitting the issues, Dallas.

[Larklen]

In regards to the teams/{team} endpoint, the documentation matches the actual output so you may want to ensure you are properly requesting v5.

Just pulled a team on v5 and this is what my response was (matches v5 docs):

[Six]

I know the documentation matches, that wasn’t what I was trying to describe. The structure of the response makes it seem like you’re getting back a list of users, but you’re actually getting back a list of channels, only labeled as users.

[Larklen]

Ah my bad, I made the assumption given the topic it was posted within

[Six]

All good haha. I just figured I would keep post here instead of flooding the forum with threads for every little thing.

[DallasNChains]

@Six The follows bug was in the original post–second example. I responded about that one. Those _links fields shouldn’t be there and there is an open issue with the team. I’ll ask about the user->channel change.

[Six]

Ah, sorry, i must have glossed over that when posting.

[scagood]

I know I’m a tad late but I didn’t want to start another thread so

Here is another case where the x-api-version is not showing up

Here is the same clientId working showing the x-api-version header

[DallasNChains]

@scagood This is a bug that will be fixed API-wide once it is fixed. Thanks for the report!