liveBook · Manning

Atomic type

As explained in The Design of Web APIs, Second Edition

A data type is a classification that specifies the kind of value a data element can contain and how it may be represented or processed.

An atomic type classifies a single value as a string, number, or Boolean, rather than an object or array. Choosing one is part of modeling each API property: first identify the data consumers need, then choose its type, name, and whether it is required. section 6.1.3 section 5.2.5

A product property

A Product can have an integer productReference and an object supplier. The reference needs a suitable atomic type; the supplier needs its own properties. A resource model can then supply consistent inputs and outputs—for example, a request to add a product omits a reference generated by the server. section 5.1.3

Check the consumer experience before settling on a type or format:

  • Use a clearly named Boolean when two values suffice. Consider an enumeration when the data may need more than two values. section 8.5 section 15.6.3
  • Check whether a number should instead be formatted as a string, and prefer human-readable date and time formats over values consumers must decode. section 8.5 section 8.0
  • Keep request and response bodies as objects. An atomic response cannot gain additional fields without changing its shape; an array of atomic IDs has the same limitation for each element. Strings can still suit self-sufficient values such as tags. section 15.6.3

A value can be valid yet awkward to use: {"ec":50400} makes consumers decode a washing machine’s end-of-cycle time, while {"endOfCycle":"2-35"} uses a nonstandard format. Model the chosen types in a JSON Schema, but revisit them for usability and interoperability rather than treating a working model as finished. section 8.0 section 7.4

How The Design of Web APIs, Second Edition covers it

How deep it goes
Explains basic atomic types and practical format and extensibility trade-offs, without descending into implementation internals.
Examples
Uses an integer product reference, encoded end-of-cycle values, owner ID arrays, and string tags.
What it assumes
Introduces strings, numbers, and Booleans as basic portable types and briefly introduces YAML alongside JSON.
What you can do after
Apply it via JSON Schema to model property types, then evaluate formats and atomic values for consumer usability and future changes.
How it connects
Connects atomic types to JSON Schema, resource modeling, objects, arrays, formats, and interface extensibility.

Also explained in

Compare how 17 books explain atomic type →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.