Page MenuHomePhabricator

Reformat pageview API responses to allow for status reports and messages {slug}
Closed, ResolvedPublic

Description

At the moment, if you ask for missing data the pageview API simply 404s. My suggestion would be a 200 with an error code and message.

As the author of client libraries for RESTful APIs, one of the things I've most often seen (and most often appreciated) is when you have a return type of a JSON blob divided into "status", "message" and "content" - where "message" contains an error or warning message if status is "error", or similar. It's a lot easier and more obvious to process than a HTTP status code.

The reason for this is very simple: RESTful APIs tend to be built around a multivariable directory structure. A HTTP status just tells you 'your multiple variable choices, taken together, did/did not work". That's of limited utility for client debugging. As an example:

https://wikimedia.org/api/rest_v1/metrics/pageviews/aggregate/en.wikipedia/all-access/user/daily/2013100100/2013100100

That 404s. Now, does that 404 mean:

  1. en.wikipedia isn't a valid project
  2. en.wikipedia is a valid project but it doesn't have all-access data yet
  3. It is a valid project, it does have that data, but not at daily granularity
  4. All of those things are true but my timestamps are wrong.

On the other hand, what actually happened is communicated nicely by:

{
"status": ["error"],
"message": ["We do not have data covering the time range you asked
for. Please see the API documents at
https://wikimedia.org/api/rest_v1/?doc"],
"content": []
}

This also covers more hairy problems, like https://wikimedia.org/api/rest_v1/metrics/pageviews/aggregate/fa.wikipedia/all-access/user/daily/2015090100/2015102200
(an example provided by Leila. Thanks Leila!): it's asked for data September to October but only has the October data. Why? Well, presumably it hasn't loaded the September data yet. So at the moment, it 200s, while only giving some of what the user asked for, with no indication that it is missing data. If the status/message elements existed, you could do:

{
"status": ["warning"],
"message": ["Some of the data you asked for could not be found; we
have returned the elements that could. Please see the API documents at
https://wikimedia.org/api/rest_v1/?doc"],
"content": [...]

Event Timeline

Ironholds raised the priority of this task from to Needs Triage.
Ironholds updated the task description. (Show Details)
Ironholds added a project: Analytics-Backlog.
Ironholds added a subscriber: Ironholds.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 29 2015, 3:50 AM
Nuria added a subscriber: Nuria.EditedOct 30 2015, 3:49 PM

Action item: Document error codes appropriately in wikitech.
Top page: https://wikitech.wikimedia.org/wiki/Analytics/PageviewAPI/

Nuria set Security to None.
Nuria renamed this task from Reformat pageview API responses to allow for status reports and messages to Reformat pageview API responses to allow for status reports and messages {slug}.Oct 30 2015, 3:56 PM
Milimetric moved this task from Next Up to In Progress on the Analytics-Kanban board.

Addressed in this pull request: https://github.com/wikimedia/restbase/pull/396

@Ironholds: we can improve the situation a bit but not completely. Details:

  • return a nice response that mentions some of the data in the requested range is not available. This sounds nice but it would require us to inspect the results of every request (potentially a lot of requests and potentially a lot of results). And to go through and match the date keys with the request keys. That's easy as cake to code but I'm not a fan of how much CPU it would take in aggregate.
  • changing the shape of the return to always be a 200 with potential error messages contained in the body of the response. This won't fly with the RESTBase team, which believes quite strongly in using meaningful HTTP status codes. I also agree with them, this is not an interface for a human (someone could easily build that as a layer on top of the API). It's an interface for a computer, and the agreed-upon standard that computers talk about status on the internet is HTTP status codes.

So we addressed what you said keeping those things in mind.

Restricted Application added a subscriber: StudiesWorld. · View Herald TranscriptNov 3 2015, 9:06 PM
Nuria closed this task as Resolved.Nov 16 2015, 7:53 PM

Noting that I've already received user complaints on this (which could be solved with the "make it possible to see which date ranges are covered" bug.

@Ironholds: so far we're still of the same opinion. Filling the holes and/or adding more information to these responses should be the job of a higher level API or API client. In the case of the complaints you get, you could easily do that hole-filling stuff in your client with the same strategy that we would use (multiple requests to the API). I know this is a crappy answer, but we're just worried about adding too much complexity and performance overhead to the API until we get a better sense of what the usage is going to be. If six months from now our performance is pretty even and we think we can easily add features like this, we'll totally do that.

Multiple requests to the API? Just hit it over and over again until it 404s to identify the range of data?

Nuria added a comment.Nov 30 2015, 7:45 PM

@Ironholds: I think part of the problem can be fixed with docs. We should certainly document that the pageview API will never have data older than May 2015, for example. As @Milimetric mentioned this would be the clients, not the server, responsibility. A thickish client should not send the reqeuest if the data you are asking for is older than May 2015 or newer than the date of today.

There are other more complicated cases that will return "partial" data but, until we see usage patterns we will not be addressing those as there are many caveats (need to look for ticket in which we listed those).

Agreed, never older than May, but are you planning on clearing old data out as new data comes in for storage purposes?

Agreed, never older than May, but are you planning on clearing old data out as new data comes in for storage purposes?

So far, no. I think we'd decrease resolution to weekly maybe monthly before we removed it completely. But the main problem is really the fact that there are lots and lots of articles. If we run out of space and people need this old data, we'll have to bring it up with the budgeting process.