APIs for analysts

Why it matters

Most integrations today are built on APIs (application programming interfaces). An analyst who can read an API specification can answer questions that would otherwise wait days for a developer: "Does the vendor's API give us the loyalty balance?", "Can we filter orders by date?", "What happens if the customer does not exist?" You do not need to write the integration code, but you do need to specify it precisely and test that it behaves as the requirements say.

The core idea: requests and responses

A web API (usually REST over HTTPS) works like a structured conversation. The client sends a request:

• Method: what to do. GET reads, POST creates, PUT or PATCH updates, DELETE removes.
• URL: which resource, for example https://api.example.com/v1/customers/1042. Parts after ? are query parameters, such as ?status=active&limit=50.
• Headers: metadata, such as Authorization: Bearer <token> and Content-Type: application/json.
• Body: the data sent with POST, PUT or PATCH, usually JSON.

The server returns a response with a status code and usually a JSON body:

Reading a specification

Most modern APIs publish an OpenAPI (formerly Swagger) specification, often rendered as interactive documentation. A fragment:

paths:
  /customers/{id}/points:
    get:
      summary: Get a customer's loyalty balance
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Balance found
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerId: { type: string }
                  balance:    { type: integer }
                  asOf:       { type: string, format: date-time }
        "404":
          description: Customer not found

From this an analyst can write: "POS calls GET /customers/{id}/points at checkout. On 200, show balance. On 404, show 'No loyalty account' and offer sign-up. On any 5xx or no reply in 2 seconds, continue the sale without points and log the failure." That sentence is an integration requirement a developer can build and a tester can check.

Things to look for in any spec: authentication method, rate limits, pagination (how to get page 2 of results), date and time formats and time zones, required versus optional fields, error formats, and versioning (what happens when v2 arrives).

Worked example: testing calls yourself

You can test a public practice API with curl in a terminal, or with a graphical client such as Postman, Insomnia or Bruno. JSONPlaceholder (jsonplaceholder.typicode.com) is a free fake API made for practice:

curl -i https://jsonplaceholder.typicode.com/users/1
curl -i "https://jsonplaceholder.typicode.com/posts?userId=1"
curl -i https://jsonplaceholder.typicode.com/users/9999
curl -i -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "body": "Hello", "userId": 1}'

The -i flag shows the status line and headers. The first call returns 200 with one user; the second filters with a query parameter; the third returns 404; the fourth returns 201 with the new record (the fake API does not really save it). Writing down what you sent and what came back is the start of an interface test plan.

Security notes

Never paste real production credentials or customer data into an online tool, a shared Postman workspace or a chat. Use test environments ("sandbox" accounts) and test data. API keys belong in the tool's secret storage or environment variables, not in saved requests you share.

Common mistakes

• Specifying only the happy path; every interface needs rules for 4xx, 5xx and time-outs.
• Ignoring pagination and assuming the first page is all the data.
• Time zones: 2026-03-16T23:30:00Z is already the 17th in many places.
• Assuming field meanings from names; confirm with the spec and sample data.

Quick recap

• A request has a method, URL, headers and optional body; the response has a status code and usually JSON.
• OpenAPI specs tell you endpoints, parameters, fields and errors; turn them into precise integration requirements.
• Test with curl or Postman against sandboxes, and never with real credentials or customer data in shared tools.

Try it

In the Do tab you read a real spec and test calls against a free practice API.