API Testing

What it is

API testing exercises the service through its interface rather than its UI. You send requests (or invoke RPCs) and assert on status codes, headers, payload shape, business rules and error contracts. Because an API is the contract every client depends on, it is the highest leverage place to test behaviour.

1
client ──request──▶ API ──▶ service ──▶ datastore
2
       ◀─response──         (status, body, headers, errors)

Three interface styles dominate, and each needs a different testing stance:

REST — resource URLs, HTTP verbs, JSON. Validate status codes, media types and schema.
GraphQL — one endpoint, typed schema, arbitrary queries. Validate resolvers, nullability, error paths and query depth limits.
gRPC — protobuf contracts, HTTP/2 streams. Validate message schemas, status codes and deadline/cancellation behaviour.

When to use it / when to avoid it

Use it for

Verifying the request/response contract every client relies on
Business rules the UI hides or cannot reach (pagination edges, auth scopes, rate limits)
Fast, stable regression coverage that runs without a browser
Validating error handling: 4xx messages, 5xx behaviour, validation failures

Avoid it when

You are re-asserting the same rule already covered by a faster unit or integration test
You need to verify rendering, accessibility or interaction — that is end-to-end
You want to test internal implementation detail rather than the published interface

Frameworks & tools

Tool	Ecosystem	Notes
Postman / Newman	Any	GUI authoring plus CLI runner for CI
REST Assured	Java	Fluent DSL over REST endpoints, JUnit-friendly
Karate	Java / JVM	BDD-style API tests, built-in mocking and Gatling perf
Schemathesis	Python	Property-based, generates cases from OpenAPI/Swagger
Bruno	Any	Git-friendly, offline, plain-text collections
Robot Framework + RequestsLibrary	Python	Keyword-driven REST testing, easy to read and extend
Playwright APIRequestContext	Multi	Reuse browser fixtures for pure API checks
grpcurl / ghz	Go	gRPC reflection calls and load testing
Dredd	Node	Validate implementation against API Blueprint/OpenAPI

Quick setup

1
npm install -D vitest supertest
2
npm install -g newman
3
newman run collection.json

1
pip install requests schemathesis robotframework robotframework-requests
2
schemathesis run --checks all https://api.example.com/openapi.json

1
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
2
go get github.com/stretchr/testify

1
<dependency>
2
  <groupId>io.rest-assured</groupId>
3
  <artifactId>rest-assured</artifactId>
4
  <version>5.5.0</version>
5
  <scope>test</scope>
6
</dependency>

1
dotnet add package RestSharp
2
dotnet add package xunit

Example

1
import request from 'supertest';
2
import { app } from '../src/app';
3

4
it('rejects a user without a name', async () => {
5
  const res = await request(app).post('/users').send({ name: '' });
6
  expect(res.status).toBe(422);
7
  expect(res.body.errors[0].field).toBe('name');
8
});

1
import requests
2

3
def test_create_and_read(base_url):
4
    created = requests.post(f"{base_url}/users", json={"name": "Ada"})
5
    assert created.status_code == 201
6

7
    uid = created.json()["id"]
8
    fetched = requests.get(f"{base_url}/users/{uid}")
9
    assert fetched.status_code == 200
10
    assert fetched.json()["name"] == "Ada"

1
*** Settings ***
2
Library    RequestsLibrary
3

4
*** Variables ***
5
${BASE_URL}    http://localhost:8000
6

7
*** Test Cases ***
8
Tao Roi Doc Lai User
9
    Create Session    api    ${BASE_URL}
10
    ${body}=    Create Dictionary    name=Ada
11
    ${created}=    POST On Session    api    /users    json=${body}
12
    Should Be Equal As Integers    ${created.status_code}    201
13
    ${uid}=    Set Variable    ${created.json()}[id]
14
    ${fetched}=    GET On Session    api    /users/${uid}
15
    Should Be Equal    ${fetched.json()}[name]    Ada

1
func TestCreateUser(t *testing.T) {
2
  body := strings.NewReader(`{"name":"Ada"}`)
3
  res, err := http.Post(baseURL+"/users", "application/json", body)
4
  if err != nil {
5
    t.Fatalf("request failed: %v", err)
6
  }
7
  defer res.Body.Close()
8
  if res.StatusCode != http.StatusCreated {
9
    t.Fatalf("want 201, got %d", res.StatusCode)
10
  }
11
}

1
import static io.restassured.RestAssured.*;
2
import static org.hamcrest.Matchers.*;
3

4
@Test
5
void createsUser() {
6
  given()
7
    .contentType(ContentType.JSON)
8
    .body("{\"name\":\"Ada\"}")
9
  .when()
10
    .post("/users")
11
  .then()
12
    .statusCode(201)
13
    .body("name", equalTo("Ada"));
14
}

1
[Fact]
2
public async Task CreatesUser()
3
{
4
    var client = new RestClient(baseUrl);
5
    var req = new RestRequest("/users", Method.Post)
6
        .AddJsonBody(new { Name = "Ada" });
7

8
    var res = await client.ExecuteAsync(req);
9
    Assert.Equal(HttpStatusCode.Created, res.StatusCode);
10
}

Anti-patterns & best practices

Assert on the contract, not the implementation. Check status, schema and semantics the client was promised, not private field ordering.
Validate the schema automatically. Run Schemathesis, Dredd or JSON-schema checks so coverage scales beyond hand-written cases.
Test the unhappy paths. Empty bodies, wrong types, missing auth, oversized payloads and rate limits are where APIs break.
Keep collections in version control. Bruno and Newman make collections diffable; stop sharing exported Postman JSON by email.
Seed and clean via the API itself where possible, and isolate data per run so tests are order-independent.
Do not chase 100 percent endpoint coverage. Prioritise endpoints on critical client paths.