API Design Principles

Purpose

APIs are contracts between systems and teams. AIC APIs must be predictable, secure, documented and versioned.

Principles

1. Resource-oriented design

Model APIs around resources and use HTTP methods consistently.

GET    /v1/cases
GET    /v1/cases/{caseId}
POST   /v1/cases
PATCH  /v1/cases/{caseId}
DELETE /v1/cases/{caseId}

2. Stable contracts

Do not expose internal entities directly. Use request and response models.

3. Explicit errors

Use consistent ProblemDetails responses.

4. Secure by default

Endpoints require authentication unless explicitly public. Authorization policies must be deliberate.

5. Observable by default

APIs must log correlation identifiers, request outcome, latency and important domain events.

6. Backward compatible by default

Breaking changes require versioning and consumer communication.

Request Design

Good requests:

• contain only fields the client is allowed to set

• validate at boundaries

• use clear names

• avoid leaking database structure

• avoid ambiguous optional fields

Response Design

Good responses:

• are stable

• include identifiers where needed

• avoid internal implementation details

• use UTC for timestamps

• use consistent casing

• document nullability

HTTP Status Code Standard

Scenario	Status
Successful read	200
Successful create	201
Successful command without body	204
Validation failure	400
Unauthenticated	401
Authenticated but forbidden	403
Not found	404
Conflict / concurrency	409
Unsupported media type	415
Rate limited	429
Server error	500
Dependency unavailable	503

API Review Checklist

• Is the API contract stable?

• Are request and response DTOs separate from entities?

• Are errors consistent?

• Is authorization tested?

• Is OpenAPI generated?

• Are pagination and filtering defined?

• Are breaking changes understood?

• Are operational behaviours documented?