[Mediawiki-api] [Mediawiki-api-announce] BREAKING CHANGE: HTTP 503 status code for maxlag errors

[Carl Fürstenberg]

On Thu, Jul 16, 2009 at 04:40, Brad Jorsch<b-jorsch at northwestern.edu> wrote:
> On Wed, Jul 15, 2009 at 11:30:40PM +0200, Roan Kattouw wrote:
>>
>> As of r52190 [1], API maxlag errors (the kind of error you get when
>> you set &maxlag=2 and the maximum slave lag is higher than two
>> seconds) return a HTTP 503 status code rather than a 200, for
>> consistency with index.php (which does the same thing).
>
> I agree with the others, this change should be reverted, as it is an
> arbitrary breaking change that makes things more difficult for API
> clients for consistency with something that is not really related.
>
> index.php returns an HTTP 503 error because it speaks HTTP, and that's
> how you return errors in HTTP. But the API doesn't speak HTTP, it just
> uses HTTP as a ''transport layer'' and reports its errors using its own
> protocol. This change raises maxlag from an API-level error (where it
> belongs) to a transport-level error; it's the same as if we would have
> index.php return an ICMP error for maxlag.
>
>> Be aware that some client libraries may treat the 503 return code
>> differently, which is why this could be a breaking change.
>
> That's an understatement. Any logically-coded client library that
> bothers to check for errors will probably work something like this:
>
>  $response = send_http_request($uri, $postdata);
>  if ($response->is_http_error()) {
>      // Handle error
>      return null;
>  }
>
>  $result = parse_api_response($response->get_content());
>  if ($result == null) {
>      // Handle "unparsable response" error
>      return null;
>  }
>
>  // Any special API error logging/handling here
>
>  return $result;
>
> As a result of r52190, that must become rather more complicated:
>
>  $response = send_http_request($uri, $postdata);
>
>  if ($response->http_status_code() == 503) {
>      // Maybe a maxlag error? Or maybe a real HTTP error, in which case
>      // parse_api_response() should fail?
>      $result = parse_api_response($response->get_content());
>      if ($result != null) {
>          // Any maxlag-specific special error logging/handling here
>          return $result;
>      }
>  }
>
>  if ($response->is_http_error()) {
>      // Handle error
>      return null;
>  }
>
>  $result = parse_api_response($response->get_content());
>  if ($result == null) {
>      // Handle "unparsable response" error
>      return null;
>  }
>
>  // Any special API error logging/handling here
>
>  return $result;
>
> _______________________________________________
> Mediawiki-api mailing list
> Mediawiki-api at lists.wikimedia.org
> https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
>

I don't agree with your notion at all. max-lag should be handled
outside the normal API system, and should be returned as 503. The
nevessary headers are allready there, so your argument that you would
need to  parse the api-response twice is just wrong; Following pseudo
code would be how maxlag should be handled:

function handle_response() {
if status == 503
  sleep( get_header_value( "Retry-After" ) )
  http_post( this->post, this->handle_response )
  return
endif

parse_api()
blablabla()
}

I ask roan to undo the undo and let it be using 503 instead of 200, as
200 makes it more difficult to handle (would need to search for
certain headers at each call and make string matching) this error in
the correct way (in that the api should be fully bypassed)
-- 
/Carl Fürstenberg <azatoth at gmail.com>