Building API Requests

Why it matters

A request built wrong tests nothing, or tests something else. Put a filter in the body of a GET and many servers ignore it and return the full list, so "the list loads" passes while the filter was never exercised. Leave an & unencoded in a search term and the server receives two parameters instead of one.

Controlling every part of the request also makes real defects easier to pin down: you change one input at a time, reproduce a bug without the user interface, and give developers a request they can run.

Four places an input can go

Start from the API reference. Many teams publish it as an OpenAPI document: a standard, machine-readable description of a REST API, written in YAML or JSON. There each parameter has an in field that names its location, such as path, query or header, and the body is described under requestBody. The excerpt below is the endpoint of the worked example.

• Path parameters identify the resource, like {customerId} in /customers/{customerId}. They are always required; replace the whole placeholder, braces included.
• Query parameters refine the request: filter, sort, page, search or switch an option. They are usually optional with a default, so leaving one out is a test case too. Percent-encode reserved characters in values.
• Headers describe the request: Content-Type what the body is, Accept what you want back, Authorization who is calling. OpenAPI does not list these three as parameters: requestBody, the responses and security determine them.
• The body carries the data you create or change. RFC 9110 gives content in a GET or DELETE request no generally defined meaning, so those requests normally have none.

# server: https://api.example.com/api/v1
/customers/{customerId}/addresses/{addressId}:
  patch:
    parameters:
      - name: customerId
        in: path
        required: true
        schema: { type: integer }
      - name: addressId
        in: path
        required: true
        schema: { type: integer }
      - name: notify
        in: query
        required: false
        description: Send the customer an SMS about the change
        schema: { type: boolean, default: true }
    requestBody:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/AddressChange' }
    responses:
      '200':
        description: The updated address
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Address' }
    security:
      - bearerAuth: []

Try it: OpenAPI Viewer

Request bodies: JSON, form and multipart

The Content-Type header must describe the bytes you actually send. Three formats cover most APIs; the sample sends the same rating in each.

• application/json: the usual format for REST APIs. It keeps types — 4 is a number, "4" a string — and nests objects and arrays.
• application/x-www-form-urlencoded (WHATWG URL Standard): the classic HTML form format, name=value pairs joined by &, percent-encoded, with a space written as +. Every value is text. Some login and token endpoints require it.
• multipart/form-data (RFC 7578): for file uploads. The parts are separated by a boundary declared in Content-Type; let the client generate it, because a hand-typed multipart/form-data without the boundary cannot be parsed.
• A format the endpoint does not accept should be refused, typically with 415 Unsupported Media Type — a useful negative test.

POST /api/v1/stores/riyadh-01/feedback HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"rating": 4, "subscribe": true}

POST /api/v1/stores/riyadh-01/feedback HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

rating=4&subscribe=true

POST /api/v1/stores/riyadh-01/feedback HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=x7Kq9

--x7Kq9
Content-Disposition: form-data; name="rating"

4
--x7Kq9
Content-Disposition: form-data; name="photo"; filename="box.jpg"
Content-Type: image/jpeg

(the bytes of the image)
--x7Kq9--

Try it: API Payload Builder Try it: Request Body Inspector

Worked example: from the contract to the request

A test case says: change the city of address 3 of test customer 58 to Jeddah and the postal code to 23436, without sending the customer an SMS. Work through the excerpt above, one input at a time.

• Method: the contract defines patch for this path — a partial change.
• Path: the server URL plus the path with both placeholders replaced: /api/v1/customers/58/addresses/3.
• Query: notify sends the SMS and defaults to true, so leaving it out would send one; add ?notify=false.
• Headers: Content-Type: application/json from requestBody, Accept: application/json from the response, and Authorization with the bearer token of a test account, from security.
• Body: only the changed fields, typed as the schema defines them. The $ref points to the AddressChange schema elsewhere in the document, which defines city and postalCode as strings, so the postal code goes in quotes: {"city": "Jeddah", "postalCode": "23436"}.
• Variants: change one part at a time — send postalCode as a number, use an address that belongs to another customer, remove Content-Type — so each result points to one input.

Part 1:1PATCH /api/v1/customers/Part 2:258/addresses/Part 2:23?Part 3:3notify=false HTTP/1.1
Part 4:4Host: api.example.com
Part 5:5Content-Type: application/json
Accept: application/json
Part 6:6Authorization: Bearer eyJhbGciOi...

Part 7:7{"city": "Jeddah", "postalCode": "23436"}

PATCH /api/v1/customers/58/addresses/3?notify=false HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGciOi...

{"city": "Jeddah", "postalCode": "23436"}

Try it: API Query Parameter Builder Try it: API Header Builder

Sending it with an API client

A graphical API client — Postman, or the Mutqan API Request Builder in the browser — turns these decisions into fields: method, URL, a parameter table, a header table, authorisation and a body editor. cURL, a command-line client, turns them into options such as -X, -H and -d. The habits matter more than the tool:

• Keep the base URL, test account and token in variables (Postman writes {{baseUrl}}), so one saved request runs on every environment.
• Enter query parameters in the table and pick the body type, so the client builds the query string and sets Content-Type; if you also type that header, make the two agree. Clients differ in which characters they encode, so check that a value such as tea & coffee arrives as one parameter.
• Check what was actually sent: clients add headers you did not type, such as User-Agent. Send the request once to a capture URL of the Mutqan HTTP Request Inspector and compare.
• Export the request as cURL for bug reports, with the token replaced by a shell variable such as $TOKEN. The sample uses bash quoting; the Mutqan cURL Generator also writes PowerShell and Windows cmd versions.
• In cURL, -d sends the body and makes the method POST unless -X sets another; without a Content-Type header it labels the body application/x-www-form-urlencoded, even when it is JSON.

curl -X PATCH "https://api.example.com/api/v1/customers/58/addresses/3?notify=false" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"city": "Jeddah", "postalCode": "23436"}'

Try it: API Request Builder Try it: cURL Generator Try it: HTTP Request Inspector

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.
• OpenAPI SpecificationOpenAPI InitiativeThe standard for describing REST APIs: paths, operations, parameters, schemas, responses and security schemes.
• URL StandardWHATWGHow browsers actually parse, serialize and encode URLs, including application/x-www-form-urlencoded.
• RFC 7578: Returning Values from Forms: multipart/form-dataIETF · 2015The multipart/form-data encoding used for file uploads and mixed form submissions.