API Response Validation

Why it matters

APIs fail in ways a quick look does not reveal. A 200 OK can carry an error message in its body, a number can quietly become a string, a total can leave out an item, and a profile response can include a password hash. Every client of the API, whether a web app, a mobile app or a partner integration, inherits these defects, often without noticing until something breaks.

Validation also decides what a test is worth. A test that checks only the status code passes whenever the server answers, which gives false confidence. Precise assertions turn each run into evidence: a failed assertion names the field, the expected value and the actual value, which is most of a good bug report.

Seven layers of a response check

Read a response from the outside in. The status line says what happened, the headers describe the message and the body carries the data. Inside the body, check structure first (are the fields there?), then types, then values, and finally the rules that connect several values. Timing is not written in the response; your client measures it, but it belongs to the same check.

Every assertion needs a test oracle, the source of the expected result: the API documentation, the acceptance criteria or a business rule, never the response itself. The example in this lesson is the response to a request that created an order for customer 7 with two items.

• Status code: exactly the documented code. A created resource returns 201, not "any 2xx". Assert the number; the reason phrase ("Created") is informational only, and HTTP/2 does not send one.
• Headers: Content-Type gives the media type of the body, here application/json; after a 201, a Location header identifies the new resource. RFC 9110 makes header names case-insensitive, so compare them that way.
• Fields present: every required field exists, and fields that must never be sent, such as password, are absent.
• Types: id and customerId are integers, total is a number and items an array. "7" in quotes would be a string: a type defect even though the value looks right.
• Values: what you sent comes back unchanged (customerId is 7), enumerations are in the allowed set (status is pending), and formats are right (createdAt is an RFC 3339 timestamp ending in Z or an offset).
• Business rules: values agree with each other. total is 2 × 99.95 + 1 × 50.00 = 249.90, and the number at the end of Location equals id.
• Timing: the response arrives within the budget the team agreed for this endpoint. Here the client measured 184 ms against a budget of 1,000 ms in the test environment.

HTTP/1.1 Part 1:1201 Created
Part 2:2Content-Type: application/json
Location: /api/v1/orders/9021

{
  Part 3:3"id": 9021,
  Part 4:4"customerId": 7,
  Part 5:5"status": "pending",
  "items": [
    { "sku": "A-100", "qty": 2, "unitPrice": 99.95 },
    { "sku": "B-200", "qty": 1, "unitPrice": 50.00 }
  ],
  Part 6:6"total": 249.90,
  "createdAt": "2026-10-01T09:30:12Z"
}

response time: Part 7:7184 ms

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/orders/9021

{
  "id": 9021,
  "customerId": 7,
  "status": "pending",
  "items": [
    { "sku": "A-100", "qty": 2, "unitPrice": 99.95 },
    { "sku": "B-200", "qty": 1, "unitPrice": 50.00 }
  ],
  "total": 249.90,
  "createdAt": "2026-10-01T09:30:12Z"
}

Try it: API Response Validator

Pointing at fields with JSONPath

An assertion needs an address for the value it checks. JSONPath, standardised by the IETF as RFC 9535, writes that address as an expression that starts at $, the root of the document, and moves down one segment at a time: .name for an object member, [0] for an array index, [*] for every element, .. for any depth and [?(…)] for a filter, in which @ stands for the element being tested. RFC 9535 also accepts a filter without the parentheses ([?@.qty>1]), but many tools written before the standard require them, so this lesson writes them. Such tools differ in other details too, so try an expression in your own tool first.

The result is a nodelist: zero, one or many values. An empty result is not an error; it means nothing matched. That makes absence easy to assert and typos dangerous: $.totl matches nothing, so an assertion on it must fail, not pass silently. Results are parsed values, so 50.00 in the text is the number 50.

• One value: $.status must equal "pending".
• Absence: $.password must return nothing. Sensitive or internal fields are caught only by asserting that they are missing.
• Every element: select the elements that break the rule and expect an empty result. If $.items[?(@.qty<1)] returns nothing, no item has a numeric quantity below 1. A comparison skips an item whose qty is missing or is a string, so pair the rule with presence and type checks. This works in any tool, including tools that compare a value rule with the first match only.
• A count: when you expect two items, assert the length of $.items instead of checking only the first element.

Expression                   Result on the example body
$.status                     "pending"
$.items[0].sku               "A-100"
$.items[-1].unitPrice        50                   last element
$.items[*].qty               2, 1                 every element
$..sku                       "A-100", "B-200"     any depth
$.items[?(@.qty>1)].sku      "A-100"              filter
$.password                   (no match)           absent, as required

Try it: JSON Path Tester Try it: JSON Tree Viewer

Worked example: the checklist for a new order

The documentation says: "POST /api/v1/orders creates an order and returns 201 Created, a Location header with the order's URL and the order as JSON. A new order has the status pending. total is the sum of qty × unitPrice over all items."

The request sent customerId 7 and two items, A-100 × 2 and B-200 × 1. Writing one assertion per line, each with its layer and its oracle, gives a checklist you can run by hand, paste into a validator or automate later.

• Values that change on every run, id and createdAt, are checked by type, format and relationship (the Location number equals id; createdAt is close to the time of the request), never by an exact value.
• Values you control are checked exactly: you sent customer 7 and two items, so you expect them back.
• The expected total is computed with the documented rule from the items in the response: the rule, not the response, is the oracle. Compare numbers as numbers: 249.90 and 249.9 are different text but the same JSON number.
• One check reaches beyond this response: a GET on the Location URL should return the same order, which shows that it was stored, not only echoed.

#   Layer     Assertion                                      Oracle
1   status    status == 201                                  documentation
2   headers   Content-Type contains application/json         documentation
3   headers   Location == /api/v1/orders/{id}                documentation
4   fields    $.id, $.status, $.items, $.total exist         documentation
5   fields    $.password does not exist                      security rule
6   types     $.id integer, $.total number, $.items array    documentation
7   values    $.customerId == 7, $.items length == 2         the request
8   values    $.status == "pending"                          business rule
9   values    $.createdAt is RFC 3339 with Z or an offset    documentation
10  rule      $.total == sum of qty * unitPrice (249.90)     business rule
11  timing    response time <= 1000 ms (measured: 184 ms)    team budget

Try it: REST API Tester

What to assert in every response, and what not to

Not every endpoint needs eleven checks, but every response deserves a minimum, error responses included: an error response gets the exact documented 4xx code, a JSON content type and an error body with the documented shape.

• Always: the exact status code, the Content-Type media type, a body that parses as JSON, the required fields and the absence of forbidden ones. A 204 No Content response has no body, so for it you assert only the status and the headers.
• Data you sent or can predict: exact values. Generated data such as ids, timestamps and tokens: type, format, range and relationships.
• Business rules: at least one assertion for each rule the endpoint implements.
• Timing: a budget check on every call. One slow sample is a reason to measure again, not yet a performance defect.
• Not significant, so do not assert it: the order of members in a JSON object (RFC 8259 defines an object as unordered), the order of headers with different names, the letter case of header names and whitespace in the body.
• Array order: assert it only when the API documents a sort order, and then assert it explicitly.

Try it: API Response Analyzer

Frequently asked questions

References

• RFC 9110: HTTP SemanticsIETF · 2022The meaning of HTTP methods, header fields, status codes and content negotiation, independent of the wire version.
• RFC 9535: JSONPath: Query Expressions for JSONIETF · 2024The standard JSONPath syntax — root, child, descendant, wildcard and filter selectors — and how a query is evaluated.
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange FormatIETF · 2017The JSON grammar: objects, arrays, strings, numbers, the three literals, and UTF-8 as the interchange encoding.
• ISTQB GlossaryISTQBThe standard definitions of testing terms — test case, regression testing, severity, priority, boundary value analysis and the rest.