API Validation Guidance

[jenniferoko]

API Validation Guidance

Purpose

The purpose of API validation is to verify that every Kubernetes and DNS endpoint behaves correctly under expected operating conditions following a platform patch.

Validation should confirm not only that an endpoint responds successfully, but that it returns the correct HTTP status code, response schema, resource state, and business logic.

---

General Validation Rules

Every API test should verify the following:

• Correct HTTP status code
• Expected response schema
• Required fields are present
• Returned data matches the request
• Resource state is valid
• No unexpected error messages
• API response time is acceptable
• Cleanup occurs after testing

---

HTTP Status Code Validation

Status Code	Meaning	Expected Usage
200 OK	Request completed successfully	GET, PUT
201 Created	Resource created successfully	POST
204 No Content	Resource deleted successfully	DELETE
400 Bad Request	Invalid request payload	Validation failures
401 Unauthorized	Authentication required	Protected endpoints
403 Forbidden	Access denied	Authorization failures
404 Not Found	Resource does not exist	Invalid slug
409 Conflict	Duplicate resource	Duplicate names
422 Unprocessable Entity	Validation error	Missing required fields
500 Internal Server Error	Unexpected server failure	Should never occur during smoke tests

---

Kubernetes API Validation

Test 44 — List Clusters

Validate

• HTTP 200
• Response is an array
• Every cluster contains:
  • slug
  • state
  • name
  • created_at

Example assertions

expect(response.status()).toBe(200);
expect(Array.isArray(body.data)).toBe(true);

---

Test 45 — Create Cluster

Validate

• HTTP 200 or 201
• slug exists
• state exists
• cluster identifier returned

Example

{
  "slug": "smoke-k8s-01",
  "state": "Provisioning"
}

Do not expect the cluster to be running immediately.

---

Test 46 — Poll Until Running

The API should be polled until

data.state == "Running"

Recommended polling interval

10–15 seconds

Maximum timeout

300 seconds (5 minutes)

Validate

• HTTP 200 on every poll
• state changes from:

Provisioning

↓

Running

Fail the test if

• timeout reached
• API returns 500
• state becomes Failed

---

Test 47 — Stop Cluster

Validate

• HTTP 200
• status = Success

Verify the cluster was Running before sending the stop request.

---

DNS API Validation

Test 48 — List Domains

Validate

• HTTP 200
• response array

---

Test 49 — Create Domain

Validate

• HTTP 200 or 201
• domain slug returned
• internal domain used

Example

smoke.test.internal

Never use production domains.

---

Test 50 — List Records

Validate

• HTTP 200
• response array
• record schema is valid

---

Response Schema Validation

Responses should contain expected properties.

Example Kubernetes response

{
  "status": "Success",
  "data": {
    "slug": "smoke-k8s-01",
    "state": "Running"
  }
}

Required validations

• status exists
• data exists
• slug exists
• state exists

---

Business Logic Validation

Successful HTTP responses alone are not sufficient.

Example

HTTP 200

state = Failed

This should fail the test because the business requirement is

state == Running

Always validate business outcomes in addition to transport-level success.

---

Error Validation

Unexpected responses should include

• error message
• error code
• request identifier (if supported)

Smoke tests should never receive

500 Internal Server Error

unless intentionally testing failure scenarios.

---

Performance Validation

Recommended expectations

Operation	Expected Time
GET requests	< 2 seconds
POST requests	< 5 seconds
DELETE requests	< 10 seconds
Kubernetes provisioning	≤ 5 minutes

---

Logging Requirements

Each test should log

• Endpoint
• HTTP Method
• Request Payload
• HTTP Status
• Response Time
• Resource Slug
• Final Resource State

Example

POST /kubernetes

Status: 201

Slug: smoke-k8s-01

State: Provisioning

Elapsed: 1.2s

---

Cleanup Validation

Before completing the suite verify

• No smoke-k8s-* clusters remain
• No temporary DNS domains remain
• No temporary DNS records remain

Cleanup should execute even if earlier tests fail.

---

Phase 4 Validation Checklist

• HTTP status codes verified
• Response schema validated
• Required fields validated
• Cluster reaches Running state
• Polling helper succeeds
• DNS domain created successfully
• DNS records retrieved
• No unexpected server errors
• Cleanup verified
• All Tests 44–50 pass