Developer Guide · 2025

The Complete Guide to API Testing

Everything developers need to know about testing APIs — from basic concepts to advanced techniques, with free tools and practical examples.

What is API Testing?

API testing is the process of verifying that an application programming interface (API) works correctly. Unlike UI testing — which interacts with buttons and forms — API testing communicates directly with the application layer, sending HTTP requests and validating the responses.

API tests check that:

  • Endpoints return the correct HTTP status codes
  • Response bodies contain the expected data structure and values
  • Authentication and authorization rules are enforced
  • Error responses are meaningful and correctly structured
  • Performance is within acceptable bounds (response time, throughput)

API testing is faster and more stable than UI testing because it bypasses the browser entirely. A single API test can validate business logic that would take minutes to test through a UI.

Types of API Tests

There are several distinct types of API tests, each serving a different purpose in your testing strategy.

Functional Testing

Verifies that each endpoint returns the correct response for valid inputs. This is the most common type — send a request, assert the response matches expectations.

Integration Testing

Tests how multiple API endpoints work together. For example, calling POST /orders followed by GET /orders/:id to verify the created order is retrievable.

Load & Performance Testing

Measures how an API behaves under load — response times, error rates, and throughput when handling concurrent requests.

Security Testing

Checks for authentication bypass, authorization flaws, injection vulnerabilities, and data exposure. Tests that unauthenticated requests are rejected and that users can only access their own data.

Contract Testing

Ensures the API conforms to a defined schema or contract (e.g., OpenAPI spec). Prevents breaking changes from reaching consumers without notice.

End-to-End Testing

Tests complete workflows across multiple services. Validates that a full business process — from request to database write to response — works correctly.

REST API Testing

REST (Representational State Transfer) is the dominant API architecture style on the web. RESTful APIs use standard HTTP methods and return structured data — usually JSON.

When testing a REST API, you should verify:

  1. Correct HTTP method usage — GET for reading, POST for creating, etc.
  2. Proper URL structure — resource paths follow RESTful conventions (/users/:id)
  3. Status codes — 200 for success, 201 for created, 404 for not found
  4. Response schema — JSON keys and value types match the API contract
  5. Pagination — collections return paginated results with correct metadata
  6. Error messages — errors include useful descriptions and consistent structure

# Example REST API test with Pingllo

GET https://api.example.com/users/42

Authorization: Bearer <token>

# Expected response:

{

"id": 42,

"name": "Jane Doe",

"email": "jane@example.com"

}

Use Pingllo to test REST endpoints without any setup. Paste the URL, add your auth token, and send.

GraphQL API Testing

GraphQL APIs use a single endpoint (typically /graphql) and accept queries written in the GraphQL query language. Unlike REST, the client specifies exactly what fields it needs, preventing over-fetching.

Key things to test in a GraphQL API:

  • Queries — data retrieval operations return expected fields
  • Mutations — data modification operations succeed and return updated data
  • Variables — parameterized queries handle variables correctly
  • Errors — invalid queries return descriptive errors in the errors array
  • Authorization — resolvers enforce field-level permissions

# GraphQL query example

query GetUser($id: ID!) {

user(id: $id) {

id

name

email

}

}

HTTP Methods Explained

RESTful APIs use HTTP methods (also called verbs) to define the action being performed on a resource. Understanding each method is fundamental to API testing.

MethodPurposeSafe?Idempotent?
GETRetrieve a resource✓✓
POSTCreate a new resource✗✗
PUTReplace a resource completely✗✓
PATCHPartially update a resource✗✗
DELETEDelete a resource✗✓

Safe = no side effects (read-only). Idempotent = calling multiple times produces the same result.

HTTP Status Codes Reference

HTTP status codes tell you whether a request succeeded and, if not, what went wrong. They are grouped into five classes:

1xxInformational

100 Continue, 101 Switching Protocols

2xxSuccess

200 OK, 201 Created, 204 No Content

3xxRedirection

301 Moved Permanently, 302 Found, 304 Not Modified

4xxClient Error

400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

5xxServer Error

500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

Testing tip: Always assert the exact status code in your tests, not just 2xx vs non-2xx. A 200 when you expected 201 often indicates a logic error.

API Authentication Methods

Most production APIs require authentication. Here are the common methods you'll encounter when testing:

Bearer Token (OAuth 2.0 / JWT)

Authorization: Bearer <token>

The most common method for modern APIs. The client includes a token in the Authorization header. JWTs are self-contained and can carry claims; opaque tokens require a lookup.

Basic Authentication

Authorization: Basic <base64(user:pass)>

Encodes the username and password as a Base64 string. Simple but only secure over HTTPS. Common for internal APIs and simple services.

API Key

X-API-Key: <key> (or ?api_key=<key>)

A static secret key, usually passed as a header or query parameter. Easy to implement but must be rotated if compromised.

OAuth 2.0 (Authorization Code)

(multi-step flow)

Used when users grant third-party apps access to their data. Involves redirect flows, authorization codes, and token exchanges. Required for Google, GitHub, Stripe, and most consumer APIs.

Request & Response Headers

HTTP headers carry metadata about the request or response. These are the headers you'll use and test most often:

Common Request Headers

Content-Typeapplication/json

Tells the server the format of the request body

Acceptapplication/json

Tells the server what format the client expects back

AuthorizationBearer <token>

Carries authentication credentials

X-Request-ID<uuid>

Unique request identifier for tracing and debugging

Cache-Controlno-cache

Controls caching behavior

Common Response Headers

Content-Typeapplication/json; charset=utf-8

Format of the response body

X-RateLimit-Remaining99

Requests remaining in the current rate limit window

ETag"abc123"

Version identifier for cache validation

Location/users/42

URL of the newly created resource (after 201 Created)

Access-Control-Allow-Origin*

CORS header — which origins can access this resource

API Testing Best Practices

These principles separate robust API test suites from brittle ones:

✓

Test the happy path AND error paths

Don't just test successful requests. Verify that the API returns the right error codes and messages for invalid inputs, missing auth, and non-existent resources.

✓

Use environment variables for base URLs and tokens

Never hardcode URLs or secrets in your tests. Use environment variables to switch between local, staging, and production with a single config change.

✓

Assert specific values, not just status codes

A 200 OK is necessary but not sufficient. Also assert the response body contains the expected keys, types, and values.

✓

Test idempotency where expected

Calling PUT or DELETE twice should produce the same result. Write tests that verify repeated calls don't cause unexpected side effects.

✓

Check Content-Type headers

Verify the API returns the correct Content-Type (e.g., application/json) and that your client sends it correctly in requests with bodies.

✓

Document with real examples

Save real request/response examples alongside your API documentation. Tools like Pingllo let you share request links so readers can try endpoints live.

API Testing Tools Comparison

Choosing the right tool depends on your workflow. Here's an overview of the most popular options:

Pingllo

Start Free · No Login

Browser-based API tester. No signup, no install. Supports REST and GraphQL, collections, environments, Postman import, and code generation. Best for quick testing without friction.

Get started with Pingllo →

Postman

Freemium

Industry-standard API platform. Powerful collaboration, mock servers, and automated testing. Requires an account for most features. Desktop app or web.

Insomnia

Freemium

Desktop API client with a clean UI. Strong GraphQL and gRPC support. Requires an account for sync. Recently moved to a subscription model.

Hoppscotch

Free & Open Source

Open-source, web-based API client. Very lightweight. WebSocket and SSE support. Self-hostable. Great free Postman alternative.

curl

Free · CLI

Command-line HTTP client. Powerful and scriptable. Steep learning curve for complex requests. Built into macOS and Linux. Pingllo generates curl commands for you.

Getting Started with Pingllo

Pingllo is the fastest way to start testing APIs. No signup, no install — just open and go.

  1. 1

    Open Pingllo

    Navigate to the tool at pingllo.com/tool. No account creation required — the app loads instantly.

  2. 2

    Enter your API endpoint

    Type or paste your API URL in the address bar. Choose the HTTP method (GET, POST, etc.) from the dropdown.

  3. 3

    Add headers and authentication

    Switch to the Headers tab to add custom headers. Use the Auth tab for Bearer tokens or Basic auth credentials.

  4. 4

    Build your request body

    For POST/PUT requests, switch to the Body tab. Choose JSON, form data, GraphQL, or raw text and write your payload.

  5. 5

    Send and inspect

    Click Send. View the response body, headers, status code, and timing. Use the Tree view for nested JSON or Diff view to compare runs.

  6. 6

    Save to a collection

    Save the request to a collection for reuse. Add environment variables to parameterize URLs and tokens for different environments.

Ready to test your first API?

Open Pingllo and send your first request in under 30 seconds.

Open Pingllo Free →