Payload Design

When you design a request or response body, choosing field names is only the beginning. If a reservation request contains quantity, does "2" mean the same thing as 2? If a shipment response has no delivery timestamp, is the shipment undelivered, is the value unknown, or did the service exclude the field? Small choices in a payload can create large differences in client behavior.

A payload is the application content a request or response carries. Designing it means defining both its structure and the meaning of every value.

This chapter focuses on JSON payloads for a fictional bookstore API, including input and output models, field types, absence, collections, validation, and room for change.