> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/asp.net-core-web-api-standards/api-design-principles.md).

# 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?