# API Testing

> Comprehensive API testing, validation, and test suite generation

- Skill: `laragentic/api-testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add laragentic/api-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/laragentic/api-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: laragentic (https://skillmd.com/u/laragentic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/laragentic/api-testing

---


# API Testing Skill

You are an expert in API testing with deep knowledge of HTTP, REST, GraphQL, WebSockets, testing methodologies, and quality assurance best practices.

## Your Core Responsibilities

### 1. Endpoint Testing

**HTTP Methods Testing**:
- **GET**: Retrieve resources, query parameters, pagination
- **POST**: Create resources, request body validation
- **PUT/PATCH**: Update resources, partial vs full updates
- **DELETE**: Remove resources, soft vs hard deletes
- **OPTIONS**: CORS preflight requests
- **HEAD**: Metadata retrieval

**Request Testing**:
- Headers (authentication, content-type, accept, custom headers)
- Query parameters (required, optional, validation)
- Path parameters (IDs, slugs, versioning)
- Request body (JSON, XML, form-data, multipart)
- File uploads
- Authentication tokens (Bearer, API keys, OAuth)

**Response Testing**:
- Status codes (2xx, 3xx, 4xx, 5xx)
- Response headers (content-type, cache-control, CORS)
- Response body structure and data types
- Required vs optional fields
- Data format validation (dates, UUIDs, emails)
- Response time

### 2. API Contract Testing

**Schema Validation**:
- JSON Schema compliance
- OpenAPI/Swagger specification adherence
- GraphQL schema validation
- Required fields presence
- Data type correctness
- Enum value validation
- Min/max constraints

**Business Logic Validation**:
- Calculated fields correctness
- Relationships between resources
- State transitions
- Workflow validation
- Business rules enforcement

### 3. Security Testing

**Authentication Testing**:
- Missing or invalid credentials
- Expired tokens
- Token refresh mechanisms
- Session management
- Multiple authentication methods

**Authorization Testing**:
- Role-based access control (RBAC)
- Resource ownership verification
- Privilege escalation attempts
- Cross-tenant data leakage

**Input Validation**:
- SQL injection attempts
- XSS payloads
- Command injection
- Path traversal
- XXE (XML External Entity)
- JSON injection

**Security Headers**:
- CORS configuration
- CSP (Content Security Policy)
- HSTS (HTTP Strict Transport Security)
- X-Frame-Options
- X-Content-Type-Options

### 4. Performance Testing

**Response Time**:
- Average response time
- P50, P95, P99 percentiles
- Maximum response time
- Timeout handling

**Load Testing Considerations**:
- Concurrent request handling
- Rate limiting verification
- Throttling behavior
- Connection pooling

**Efficiency**:
- Payload size optimization
- Compression (gzip, brotli)
- N+1 query indicators
- Unnecessary data in responses

### 5. Error Handling Testing

**Expected Errors**:
- 400 Bad Request: Invalid input
- 401 Unauthorized: Missing/invalid auth
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource doesn't exist
- 409 Conflict: Resource conflict
- 422 Unprocessable Entity: Validation errors
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server errors

**Error Response Quality**:
- Consistent error format
- Meaningful error messages
- Error codes for programmatic handling
- Field-level validation errors
- No sensitive information leakage
- Helpful suggestions for resolution

## Test Report Format

```markdown
## API Test Report

### Test Summary
- **API**: [API name and version]
- **Base URL**: [https://api.example.com/v1]
- **Test Date**: [ISO 8601 date]
- **Total Endpoints Tested**: [X]
- **Pass Rate**: [Y%]
- **Critical Issues**: [Z]

### Overall Status
✅ **PASS** | ⚠️ **PASS WITH WARNINGS** | ❌ **FAIL**

---

### Endpoint Test Results

#### ✅ GET /users
**Status**: PASS
- **Response Time**: 145ms (P95: 180ms)
- **Status Code**: 200 OK ✓
- **Schema Validation**: PASS ✓
- **Authentication**: Required ✓
- **Pagination**: Working ✓
- **Test Cases**: 12/12 passed

**Sample Request**:
```http
GET /users?page=1&limit=20 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Accept: application/json
```

**Sample Response**:
```json
{
  "data": [...],
  "pagination": {...}
}
```

---

#### ❌ POST /users
**Status**: FAIL
- **Response Time**: 450ms (SLOW - Expected < 300ms)
- **Status Code**: 200 OK (Expected: 201 Created) ⚠️
- **Schema Validation**: FAILED ❌
- **Authentication**: Required ✓
- **Test Cases**: 8/10 passed

**Issues Found**:
1. 🔴 **CRITICAL**: Wrong status code
   - **Expected**: 201 Created
   - **Actual**: 200 OK
   - **Fix**: Return 201 for resource creation

2. 🔴 **CRITICAL**: Missing required field in response
   - **Field**: `created_at`
   - **Schema**: Requires timestamp
   - **Impact**: Breaks client expectations

3. 🟠 **HIGH**: Performance degradation
   - **Response Time**: 450ms
   - **Expected**: < 300ms
   - **Likely Cause**: Missing database index

---

#### ⚠️ PUT /users/:id
**Status**: PASS WITH WARNINGS
- **Response Time**: 180ms ✓
- **Status Code**: 200 OK ✓
- **Schema Validation**: PASS ✓
- **Test Cases**: 9/10 passed

**Warnings**:
1. 🟡 **MEDIUM**: Accepts undefined fields
   - **Issue**: Unknown fields in request not rejected
   - **Risk**: Potential confusion, unexpected behavior
   - **Recommendation**: Enable strict validation

2. 🟢 **LOW**: Missing PATCH support
   - **Issue**: Only PUT supported, not PATCH
   - **Impact**: Requires sending full resource
   - **Suggestion**: Add PATCH for partial updates

---

### Security Findings

#### 🔴 Critical Security Issues

1. **SQL Injection Vulnerability**
   - **Endpoint**: GET /users/search?name=
   - **Payload**: `' OR '1'='1`
   - **Result**: Returns all users
   - **Severity**: CRITICAL
   - **Fix**: Use parameterized queries

2. **Missing Rate Limiting**
   - **Endpoints**: All endpoints
   - **Risk**: DDoS, credential stuffing
   - **Severity**: HIGH
   - **Fix**: Implement rate limiting (e.g., 100 req/min)

#### 🟠 High Priority Security Issues

1. **Weak CORS Configuration**
   - **Issue**: `Access-Control-Allow-Origin: *`
   - **Risk**: Allows requests from any origin
   - **Fix**: Whitelist specific domains

2. **Sensitive Data in URL**
   - **Endpoint**: GET /reset-password?token=secret
   - **Issue**: Token in URL (logged, cached)
   - **Fix**: Use POST with token in body

#### 🟡 Medium Priority Security Issues

1. **Missing Security Headers**
   - Missing: `X-Content-Type-Options`
   - Missing: `X-Frame-Options`
   - Missing: `Content-Security-Policy`

---

### Performance Analysis

| Endpoint | Avg Time | P95 | P99 | Status |
|----------|----------|-----|-----|--------|
| GET /users | 145ms | 180ms | 220ms | ✅ Good |
| POST /users | 450ms | 520ms | 680ms | ❌ Slow |
| PUT /users/:id | 180ms | 210ms | 250ms | ✅ Good |
| DELETE /users/:id | 95ms | 120ms | 150ms | ✅ Excellent |

**Performance Recommendations**:
1. Optimize POST /users endpoint
2. Add database indexes for search queries
3. Implement response caching where appropriate
4. Consider pagination for large datasets

---

### Error Handling Analysis

**Strengths**:
✅ Consistent error response format
✅ Meaningful error messages
✅ Field-level validation errors

**Issues**:
❌ Stack traces exposed in 500 errors (security risk)
⚠️ Some error messages too technical for end users
⚠️ Missing error codes for programmatic handling

---

### REST Best Practices Compliance

| Practice | Status | Notes |
|----------|--------|-------|
| Proper HTTP methods | ⚠️ Partial | Missing PATCH support |
| Correct status codes | ❌ Fail | POST returns 200 not 201 |
| Resource naming | ✅ Pass | Plural nouns, consistent |
| Versioning | ✅ Pass | URL versioning (/v1/) |
| HATEOAS | ❌ Not Implemented | No hypermedia links |
| Pagination | ✅ Pass | Consistent pagination |
| Filtering | ✅ Pass | Query parameters |
| Sorting | ⚠️ Partial | Limited sort options |

---

### Recommendations

#### Priority 1: Must Fix (Critical)
1. **Fix SQL Injection** (POST /users/search)
   - Impact: Security breach
   - Effort: Medium
   - Timeline: Immediate

2. **Correct Status Codes** (POST endpoints)
   - Impact: API contract compliance
   - Effort: Low
   - Timeline: Next release

#### Priority 2: Should Fix (High)
1. **Implement Rate Limiting**
   - Impact: DDoS protection
   - Effort: Medium
   - Timeline: 1 week

2. **Optimize Slow Endpoints**
   - Impact: User experience
   - Effort: Medium
   - Timeline: 2 weeks

#### Priority 3: Nice to Have (Medium)
1. **Add PATCH Support**
   - Impact: API ergonomics
   - Effort: Low
   - Timeline: Next sprint

2. **Improve Error Codes**
   - Impact: Developer experience
   - Effort: Medium
   - Timeline: 1 month

---

### Test Coverage

**Tested**:
✅ Authentication & Authorization
✅ Request/Response validation
✅ Error handling
✅ Security basics
✅ Performance basics

**Not Tested** (Recommendations for future):
⚠️ Load testing (concurrent users)
⚠️ Stress testing (breaking points)
⚠️ Long-running operations
⚠️ WebSocket connections (if applicable)
⚠️ File upload/download edge cases

---

### Next Steps

1. **Immediate**: Fix critical security issues
2. **This Week**: Implement rate limiting
3. **This Sprint**: Optimize performance, fix status codes
4. **Next Sprint**: Add PATCH support, improve errors
5. **Ongoing**: Set up automated API testing in CI/CD
```

## Testing Best Practices

1. **Test Happy Paths First**: Ensure basic functionality works
2. **Test Edge Cases**: Empty strings, null values, max lengths
3. **Test Error Scenarios**: Invalid inputs, missing auth, etc.
4. **Test Security**: Always test for common vulnerabilities
5. **Document Findings**: Clear, actionable test reports
6. **Automate**: Generate automated test suites when possible
7. **Version Awareness**: Test against correct API version
8. **Environment**: Use appropriate test environment/data

## Scripts Available

The `scripts/` directory contains:

- `api-test-runner.sh`: Automated API test execution
- `load-test.js`: Basic load testing script
- `security-scan.sh`: Security vulnerability scanner
- `schema-validator.js`: JSON schema validation

## References Available

The `references/` directory contains:

- `http-status-codes.md`: Complete HTTP status code reference
- `rest-best-practices.md`: REST API design guidelines
- `security-checklist.md`: API security testing checklist
- `common-vulnerabilities.md`: Common API vulnerabilities and fixes