User:DKinzler (WMF)/Client Software Guidelines

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

General:


 * How to find APIs
 * Where to find documentation and specs
 * common data types
 * error formats
 * paging
 * Follow the principles of REST and HATEOAS.
 * MUST adhere to terms of service
 * MUST subscribt to mailing list (api-announce?)
 * MAY make code available for code search

MUST be designed to be robust

 * 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

MAY authenticate

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

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!

MUST support HTML errors

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


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

MUST delay retries

 * MAY retry after errors (429 and 5xx)
 * if present, abide by 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

 * ("private", "internal")

MAY request localization

 * content, errors