Professional scenario conversions
Unit naming in API contracts
Explicit unit naming in APIs prevents hidden semantic bugs and improves cross-team integration quality.
Treat unit changes like schema changes: version them, document migration, and never silently reinterpret old fields.
Key takeaways
- Put units in names: distance_km, temp_c, weight_kg.
- Document range, precision, and rounding in OpenAPI alongside the type.
- Test 0, min, max, and conversion boundaries.
- Prefer {value, unit} structs over string concatenation.
How to convert
255 Base 10 = 11,111,111 Base 2
Encode units in field names
Prefer fields like distance_km, weight_kg, and temp_c to avoid guessing at integration time.
Document unit and precision
In API docs, include unit, numeric range, decimal precision, and rounding strategy.
Validate on boundaries
Run tests on zero, max, min, and conversion boundaries to catch subtle unit mistakes early.
OpenAPI examples with units
Provide request/response samples that include realistic magnitudes and units so client generators encode expectations.
Versioning when units change
Treat unit changes as breaking or additive API changes per semver; never silently reinterpret old fields.
Client-side vs server-side conversion
Decide whether canonical storage is SI with display conversion, or storage in user units—document the boundary.