User experience (UX) is the overall perception and interaction a person has with a product or system, including an API. API UX spans discovery, documentation, credentials, security, integration effort, pricing, reliability, and the quality of the resulting application experience. section 8.1.1
API design directly shapes UX. Unexpected crashes, vague errors, incompatible changes, silent behavior changes, and inflexible flows frustrate end users and can drive customers or API consumers to alternatives. User-friendly, interoperable APIs instead meet needs, hide unnecessary implementation details, and support efficient, adaptable applications. section 1.2.4 section 1.2.5
Sending an SMS
A developer evaluating an SMS API needs to find it, understand the documentation, obtain credentials, code a call, and trust that messages arrive promptly. An operation such as POST /messages with a 400 Bad Request response and {"error":"Missing phone number"} supports a simpler interface and clearer recovery than a cryptic operation with an unclear error. section 8.1.1 section 8.1.3
Design for UX by checking whether the API:
- Provides the operations and data consumers actually need without returning unnecessary data. section 1.2.5
- Uses clear errors, stable contracts, and backward-compatible changes to prevent confusing or silent failures. section 1.2.4
- Remains easy to discover, integrate, combine with other APIs, and adapt as client interfaces evolve. section 1.2.5 section 8.1.3
Figure 8.2 The design of an API may affect the developer and user experiences, making decision-makers think twice before choosing it (if they have a choice).
Use the figure to connect API design decisions with both developer experience and the experience of application end users. section 8.1.3
