A schema is a formal structure that defines the shape and permitted content of data in API requests or responses. It acts as a contract: fields, types, required values, ranges, lengths, and allowed alternatives determine what the API accepts. Client-side checks improve usability, but servers must validate independently because callers can bypass the client and send requests directly. section 3.3 section 1.4
Unconstrained schemas create both failure and security risks. Invalid values can cause integration problems or confusing errors; malicious values can manipulate business data, exhaust resources, inject SQL, corrupt records, or expose hidden model properties. Treat every request parameter and data source as untrusted, including responses from other services and stored database data. section 3.3 section 6.7
Constraining a book review
An unconstrained BookReview schema accepts an integer rating and an optional string review. A direct request such as POST /books/1/reviews with {"rating":500} can manipulate a book’s average rating. Very long reviews can also create resource-exhaustion problems. Constrain rating to a minimum of 1 and maximum of 5, and limit review to 2,000 characters. section 6.3
Design schemas to make invalid and dangerous behavior difficult:
- Constrain integers such as pagination values and prevent requests for impractically large collections. section 1.4
- Use enumerations for finite choices such as sort fields instead of accepting arbitrary strings. section 6.3
- Represent different data models with different schemas, make schemas reject additional properties, and separate input schemas from output schemas. section 6.7
- Validate and sanitize data at the API boundary, then validate data received from services and databases before using it. section 3.3
- Test direct requests rather than relying only on frontend controls; try invalid ranges, oversized payloads, injection strings, and unexpected fields. section 3.3 section 6.3
Figure 1.5 Every input parameter in an API represents an attack vector, including URLs, query and path parameters, request headers, and payloads. Unconstrained user input allows hackers to send malicious requests to our API to harm our system or cause unexpected behaviors.
Use the attack-vector figure to inspect how URLs, query and path parameters, headers, and payloads become dangerous when schemas leave input unconstrained. section 1.4
