An atomic data type classifies the kind of value a field can contain and how that value is represented. API design must treat types as language-agnostic choices because serialization can lose information between programming languages. Choose representations that remain understandable and usable across clients, rather than relying only on one implementation language’s type system. section 5.1 section 5.0
Choose an atomic representation deliberately, then use a richer inline type when one primitive value cannot express the field clearly.
- Use names that expose units or formats when a primitive value would otherwise be ambiguous: sizeBytes and sizeMegapixels communicate more than size. section 3.5
- Do not force several related values into a formatted string when a structured type makes their meaning and boundaries explicit. section 3.5
- Keep small, dependent concepts inline instead of promoting every data type to a resource; independent interaction and lifecycle justify separate resources. section 4.3.1
- Account for omission, empty values, nulls, primitive and collective types, and serialization behavior when specifying an API field. section 5.0
Image dimensions
A string such as dimensionsPixels: "1024x768" is technically valid but requires clients to know and unpack a special format. A richer representation makes the structure explicit: dimensions: Dimensions, where Dimensions contains lengthPixels and widthPixels. The field communicates both the values and their units without hiding multiple numbers inside one atomic string. section 3.5
Use the data-flow diagram to trace how a typed value moves from an API server through serialization to a client representation. section 5.1
