User:DKinzler (WMF)/Client Software Guidelines

This document provides guidance for client software that is accessing Wikimedia REST APIs.

General Guidance
Norms for maintainers See also:
 * How to find APIs
 * Where to find documentation and specs
 * common data types
 * error formats
 * paging
 * Who is the target audience
 * What happens if I'm not following the guidelines.
 * MUST subscribt to mailing list (api-announce?)
 * MAY make code available for code search


 * REST and HATEOAS.

SHOULD be designed to be robust against changes and failures

 * Follow the Robustness Principle.

SHOULD minimize the number of requests

 * use batching
 * use expansion
 * use normalized path (but don't over-normalize!)

SHOULD minimize the amount of data transferred

 * filter unneeded entities
 * exclude fields if not needed
 * avoid expansion if not needed

MUST specify a meaningful User-Agent header

 * or X-API-User-Agent
 * see policy

SHOULD follow redirects

 * ...unless...
 * use correct semantics for 301, 302, 303, and 308, etc

MUST surface user blocks

 * ref to block info document (403 response body)

MUST surface errors and warnings
Inform the user about:


 * server errors (5xx)
 * client errors (4xx) as appropriate

See spec for error document structure!

Inform the developer (and possibly also the user) about:


 * Deprecation headers
 * Sunset headers
 * X-WMF-Warning headers

MUST handle HTML responses gracefully

 * Errors (4xx and 5xx) may have an HTML rsponse body, rather than JSON.

MUST delay retries

 * MAY retry after errors (429 and 5xx)
 * if present, comply with the Retry-After header
 * MAY use rate limit info from response body (or header?) if present
 * wait at least 10 seconds OR implement exponential back-off
 * make an effort to avoid concurrent requests from multiple threads or processes

MUST NOT use APIs marked as restricted

 * (or "private", "internal")

MAY authenticate

 * authentication methods
 * csrf tokens
 * SHOULD use OAuth when acting on behalf of others
 * SHOULD auth when editing?

MAY request localization

 * content, errors