8 Designing user-friendly and interoperable data
Beyond simply meeting functional needs, effective APIs must present data that is easy to understand, use, and integrate. This chapter explains that user-friendliness (clarity and ease of use) and interoperability (the ability to work across systems without heavy transformation) directly influence developer experience and, ultimately, end-user outcomes. It positions these qualities as a second layer of design that follows capability modeling: once an API can do the right job, its data must be shaped so consumers can work quickly, confidently, and with minimal friction.
User-friendly, interoperable data shares several traits: it aligns with real needs, is easy to find and interpret, reduces consumer-side processing, and is consistent—preferably standardized. The chapter shows how to craft “ready-to-use” data by choosing simple yet meaningful fields, adding supporting context (such as a currency with an amount), and even providing processed values that spare clients from reimplementing business rules (for example, a safe-to-spend figure). It details choosing atomic types and formats that aid both readability and computation—avoid formatting computable numbers as strings, prefer human-readable codes or pair opaque codes with labels, and represent dates with ISO 8601, using time zones only when they’re necessary. It also emphasizes organizing data so it is discoverable and reusable: group related properties into objects, collect similar items into arrays, sort for scannability, and repeat proven substructures (like amount+currency) to boost intuitiveness and local interoperability.
Designers should focus on relevance rather than raw model size, avoiding bloated or cross-cutting models and not embedding large lists that require their own filtering and pagination. When embedding related resources, choose the minimal useful representation (ID, summary, or full) based on whether consumers must read it together with the parent. Clear naming comes last—after types and structure—so names can be simple, well-ordered, and concise, with consistent casing and without redundant prefixes, suffixes, or jargon. Finally, consistency and standardization are the glue: use coherent identifier patterns, apply the same types, formats, structures, and names for similar data across models and APIs, and prefer domain or global standards when they fit. Establishing and following design guidelines helps apply these choices uniformly, yielding APIs that are both a pleasure to use and easy to integrate.
Designing a versatile API that does the job is a good start, but we must ensure it’s user-friendly and interoperable.
The design of an API may impact the developer and user experiences, making decision-makers think twice before choosing it (hoping they have the choice).
User-friendly data helps find and interpret information easily and limits consumers' work.
Adding the address prevents consumers from reverse-geocoding the coordinates.
Different, intuitive, and interoperable representations of a location]]
Using custom or local standards or actual standards makes data interoperable.
Once we have modeled versatile data that does the job, we can revisit it to ensure it’s user-friendly and interoperable.
How to design user-friendly and interoperable data.
Designing ready-to-use data for the Bank Account model
The three possible identifiers for the Bank Account
Contrasting non-user-friendly and user-friendly data types and formats
Contrasting non-human-readable and human-readable Bank Account type codes
Organized data is easier to understand and use.
We can group data by name, position, or in objects.
Different properties representing the same type of data may be grouped into an array.
Each piece of data must be relevant.
We shouldn’t embed lists requiring filtering or pagination.
Adapt embedded resource models to needs, ensuring consumers must not systematically read them.
Fixing non-user-friendly names in the Bank Account model
We must use the same identifier for the account across models.
Inconsistent vs. consistent and user-friendly resource identifier names
Bank Account and inconsistent vs. consistent and interoperable Money Transfer models
FAQ
What does “user-friendly” vs “interoperable” data mean, and why does it matter?
User-friendly data is easy to find, understand, and use without extra processing. Interoperable data follows consistent patterns and recognized standards so different systems can exchange it without glue code. Together, they reduce developer effort, cut errors, speed integration, and improve end-user experiences.Which parts of an API should be user-friendly and interoperable?
All data surfaces: resource paths, path and query parameters, headers, request bodies, successful response bodies, and error bodies. Consistency across all of them is key.When in the design process should I optimize for user-friendliness and interoperability?
Do a secondary pass after you’ve confirmed the design meets needs. Avoid early bikeshedding (for example, debatinglongitude vs lng before you even know you need coordinates). Revisit models to refine types, formats, organization, names, and standards.How do I craft “ready-to-use” data?
- Pick simple but meaningful data (e.g., choose the most useful balance, not every possible one, unless experts need them).- Add supporting data to remove guesswork (e.g.,
balance + currency with ISO 4217 codes).- Add processed data that saves consumers work (e.g.,
safeToSpend derived from balance and overdraft).- Prefer well-known or standard identifiers/data (e.g., IBAN for accounts; ISO 4217 for currency).
What atomic types and formats make data easier to use?
- Numbers: don’t ship values for calculation as formatted strings (avoid"€1,234.5"; use 1234.5 + "EUR"). Numeric references can be formatted strings (e.g., leading zeros in account numbers).- Codes: avoid opaque values (e.g.,
7); use human-readable enums (e.g., "savings") or add a label next to a required code.- Dates/times: prefer ISO 8601 strings (e.g.,
1982-12-20T10:31:00Z) over timestamps; use timezone offsets only when necessary; let consumers localize display.How should I organize data so developers can find and interpret it quickly?
- Group related fields into objects to expose sub-concepts (e.g.,overdraftFacility: { active, limit }).- Reuse consistent, reusable sub-objects (e.g.,
{ amount, currency } for money values).- Use arrays for homogeneous sets instead of
value1..N (e.g., balances: [{ type, amount, currency, default }]).- Sort arrays and object properties for readability (document array order; place key properties first).
How do I choose the right granularity and scope for a model?
- Optimize for relevance, not arbitrary size targets; remove non-essential fields that don’t serve current or foreseeable needs.- Avoid embedding large lists that need filtering/pagination; give them dedicated resources/operations.
- When embedding related resources, choose the right representation: ID only, a summarized model, or a complete one—based on whether consumers need the details when reading the parent.
How do I design user-friendly names?
- Name last, after types/formats/structure are settled.- Use simple language; avoid jargon and cryptic abbreviations.
- Apply clear casing and hierarchy (e.g., camelCase or snake_case); order words parent-to-child.
- Be concise: drop redundant prefixes/suffixes (like model/type markers) and unnecessary words.
- Example: turn
ACTBLNDFPRTFTBKACC into overdraftFacility.active and overdraftFacility.limit.How should I pick identifiers and name them consistently?
- Prefer well-known or standard identifiers (e.g., IBAN) and use the same identifier across contexts to avoid mismatches.- Apply a naming pattern: inside the resource use
id; when referenced elsewhere use resourceNameId (e.g., accountId). Keep meaningful IDs as data too when they matter (e.g., both id and iban in an account).How do I approach consistency and standardization without hurting usability?
- Seek the widest applicable consistency: local API, organization-wide, domain (e.g., ISO 20022), or global standards (e.g., ISO 8601, ISO 4217, GeoJSON).- Reuse patterns for naming, typing, and structure across models (e.g., amounts and dates look the same everywhere).
- Balance trade-offs: some standards are less user-friendly; adopt them when they significantly boost interoperability, and document/augment them (e.g., add labels, wrap GeoJSON Point) as needed. Build design guidelines to enforce patterns.
The Design of Web APIs, Second Edition ebook for free
