# Integration Standard: REST API Design

## URL Structure
```
GET    /api/v1/orders              — list (paginated)
GET    /api/v1/orders/{id}         — get by ID
POST   /api/v1/orders              — create
PUT    /api/v1/orders/{id}         — full update
PATCH  /api/v1/orders/{id}         — partial update
DELETE /api/v1/orders/{id}         — delete

GET    /api/v1/users/{id}/orders   — nested resource (ownership)
POST   /api/v1/orders/{id}/cancel  — verb action (exception to noun rule)
```

## Request/Response Conventions

### Pagination (always paginate lists)
```json
// Request
GET /api/v1/orders?page=1&pageSize=20&sort=createdAt&order=desc

// Response
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}
```

### Error Response (RFC 7807 ProblemDetails)
```json
{
  "type": "https://api.myapp.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "One or more fields failed validation",
  "instance": "/api/v1/orders",
  "errors": {
    "userId": ["UserId is required"],
    "items": ["At least one item is required"]
  }
}
```

## Status Codes
| Code | When |
|------|------|
| 200 OK | GET, PUT, PATCH success |
| 201 Created | POST success (include Location header) |
| 204 No Content | DELETE success |
| 400 Bad Request | Malformed request body |
| 401 Unauthorized | Missing/invalid auth token |
| 403 Forbidden | Valid token, insufficient permissions |
| 404 Not Found | Resource doesn't exist |
| 409 Conflict | Duplicate/optimistic lock conflict |
| 422 Unprocessable | Validation failures |
| 429 Too Many Requests | Rate limit exceeded (include Retry-After) |
| 500 Internal Server Error | Unexpected server error |

## Versioning
- URL versioning: `/api/v1/`, `/api/v2/`
- Never version via headers (poor discoverability)
- Maintain N-1 version for 6 months before deprecating

## Minimal API Setup (.NET 10)
```csharp
var ordersGroup = app.MapGroup("/api/v1/orders")
    .RequireAuthorization()
    .WithTags("Orders")
    .WithOpenApi();

ordersGroup.MapGet("/", GetOrdersHandler)
    .WithName("GetOrders")
    .Produces<PagedResponse<OrderDto>>()
    .Produces<ProblemDetails>(400);

ordersGroup.MapPost("/", CreateOrderHandler)
    .WithName("CreateOrder")
    .Produces<OrderDto>(201)
    .Produces<ProblemDetails>(422);
```

## Security Requirements
- All endpoints require authentication (except /health, /api/docs)
- Authorization policy per endpoint (not just [Authorize])
- Rate limiting on write endpoints
- Input validation via FluentValidation
- Never expose internal IDs in error messages
