Reviewed on 9 October 2026. Good API design starts before anyone writes server code: you agree the contract, let consumers try it, and test that the implementation keeps to it. Postman supports each of those steps. This guide covers the design rules that come from the HTTP standards, a worked example of a small API, and the Postman workflow from specification to automated tests, using Postman's own documentation for each feature.
Design rules from the standards
HTTP itself settles many design questions. RFC 9110 (HTTP Semantics) is the reference.
- Safe methods. RFC 9110 defines GET, HEAD, OPTIONS and TRACE as safe: they shouldn't change server state. Never use GET for an action such as "approve" or "delete".
- Idempotent methods. PUT, DELETE and the safe methods are idempotent, so repeating the same request has the same effect as sending it once. POST is neither safe nor idempotent, which is why retried POSTs can create duplicates. Design for that, for example with a client-supplied request ID.
- Status codes with exact meanings. Use 201 Created for a successful create, 204 No Content when there's no body to return, 404 when the resource doesn't exist, 409 Conflict for a state clash, and 422 Unprocessable Content when the request is well-formed but fails validation.
- A standard error format. RFC 9457 (Problem Details for HTTP APIs), published in July 2023, replaces RFC 7807. It defines a JSON error object served as
application/problem+json, with members such astype,title,status,detailandinstance. Using it means clients don't have to learn a new error shape for every API.
Describe the contract in the OpenAPI Specification. The latest version listed there on 9 October 2026 was 3.2.1. Postman's Spec Hub documentation lists support for OpenAPI 2.0, 3.0 and 3.1, so if you plan to design in Postman, write your spec in 3.1 until Postman's documentation lists 3.2.
Keep preparing
Continue with Sarkari Resume Templates₹299 — coaching के एक महीने से काफ़ी सस्ता / far cheaper than a month of coachingWorked example: a leave-requests API
The API below is illustrative: a small HR service where employees request leave and managers approve or reject it.
| Operation | Method and path | Success | Typical errors |
|---|---|---|---|
| List my requests | GET /leave-requests?status=pending | 200 | 401 |
| Create a request | POST /leave-requests | 201 with a Location header | 422 for an invalid date range |
| Get one request | GET /leave-requests/LR-1042 | 200 | 404 |
| Cancel a pending request | DELETE /leave-requests/LR-1042 | 204 | 409 if it's already approved |
| Approve or reject | POST /leave-requests/LR-1042/decision | 200 | 403 if you aren't the approver; 409 if already decided |
The approve/reject action uses POST on a sub-resource (/decision) rather than overloading PUT. It records an action with its own rules, such as who may decide and only once.
An excerpt of the OpenAPI 3.1 description for the create operation:
openapi: 3.1.0
info:
title: Leave Requests API
version: 1.0.0
paths:
/leave-requests:
post:
summary: Create a leave request
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewLeaveRequest'
responses:
'201':
description: Leave request created
'422':
description: Validation failed
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
A validation error following RFC 9457 might look like this:
{
"type": "https://example.com/problems/invalid-date-range",
"title": "Invalid date range",
"status": 422,
"detail": "End date 2026-10-03 is before start date 2026-10-05.",
"instance": "/leave-requests"
}
The Postman workflow, step by step
1. Write the spec in Spec Hub. Postman's Spec Hub documentation describes it as the place for an API-first approach, with support for OpenAPI, AsyncAPI, protobuf, GraphQL and Smithy formats.
2. Generate a collection from the spec. The same documentation says you can generate a collection automatically from a specification and, for OpenAPI, keep the collection in sync with the spec. Treat the spec as the source of truth and regenerate rather than hand-editing requests that drift from it.
3. Add examples and a mock server. Postman's mock server guide explains that a mock simulates a real API by matching incoming requests to the saved examples in a collection. Save one example for each important response (201, 404, 409, 422) so frontend and mobile developers can build against realistic responses before the backend exists.
4. Write tests as post-response scripts. According to Postman's test script documentation, tests go in a request's, folder's or collection's Scripts > Post-response tab, and results appear under Test Results. For the create operation:
pm.test("Status is 201", function () {
pm.response.to.have.status(201);
});
pm.test("Response includes the new request ID", function () {
const body = pm.response.json();
pm.expect(body.id).to.be.a("string");
});
5. Run in CI with the Postman CLI. The Postman CLI overview documents postman collection run for running collections from a terminal or pipeline, and postman spec lint for checking a specification against your team's governance rules.
What to test for each endpoint
| Check | Example for the leave-requests API |
|---|---|
| Correct success code | POST returns 201; DELETE returns 204 |
| Response shape | The created request has an ID, status "pending" and the dates sent |
| Validation | An end date before the start date returns 422 in problem-details format |
| Authorisation | A non-approver's decision request returns 403 |
| State rules | Cancelling an approved request returns 409 |
| Idempotency | Repeating the same DELETE doesn't cause a server error |
| Not found | An unknown ID returns 404, not 500 |
Design review checklist
- Resource names are plural nouns, and actions with business rules are modelled explicitly
- GET never changes state
- Every operation lists its success and error codes in the spec
- Errors use one documented format, ideally RFC 9457 problem details
- Pagination, filtering and sorting parameters are named consistently
- Each important response has a saved example for the mock server
- Tests cover success, validation, authorisation and state errors
- The spec is linted and the collection is run in CI on every change
Using this in your career
API design is assessed in backend, QA and integration roles. A strong portfolio piece is a small API like the one above, with the OpenAPI file, a Postman collection with saved examples and tests, and a CI run that shows the tests passing. In interviews, be ready to explain why you chose each status code and how a client should handle a retried POST. Those reasons show more design judgement than the tool itself.