Azure REST API Guidelines FAQ & Answers

Azure REST API URI guidelines: (1) Resource-oriented URIs - use nouns, not verbs (GET /users/123/orders not GET /getUserOrders), (2) Hierarchical structure for relationships (/users/{userId}/orders/{orderId}), (3) Plural nouns for collections (/users not /user), (4) Lowercase with hyphens (/shipping-addresses not /ShippingAddresses). HTTP methods semantics: GET (retrieve, idempotent, cacheable), POST (create, non-idempotent, returns 201 Created with Location header), PUT (replace entire resource, idempotent), PATCH (partial update), DELETE (remove, idempotent). Status codes: 200 OK, 201 Created with Location header, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests, 500/503 server errors. Used by all Azure services (Compute, Storage, Cosmos DB APIs).

Azure JSON conventions: Content-Type: application/json, camelCase property names (firstName not first_name), ISO 8601 dates (2025-01-15T10:30:00Z), omit null values (reduce payload size). Pagination required for collections: default page size 50-100, max 1000 items per page. Use continuation tokens (cursor-based) for large datasets - stateless, efficient for distributed systems. Response format: {"value": [...items...], "nextLink": "/api/users?continuationToken=abc123"}. Client follows nextLink until null (end of results). Avoid offset-based pagination (page=2) - breaks with concurrent inserts/deletes, inefficient for large offsets. Filtering and sorting: OData-style query operators (?$filter=status eq 'active'&$orderby=createdDate desc) or simple params (?status=active&sort=createdDate). Support field selection (?$select=id,name,email) to reduce payload size.

Versioning: URI path versioning (/api/v1/users) or query parameter (?api-version=2025-01-15). Date-based versions for clarity (Azure uses date format). Maintain backwards compatibility across minor versions, breaking changes require new major version. Asynchronous operations (long-running tasks >2 seconds): Return 202 Accepted immediately with Operation-Location header pointing to status endpoint. Client polls GET /operations/{id} until completion (status: succeeded/failed/running). Final response includes result or error. Pattern: POST /api/deployments creates operation, returns 202 with Operation-Location: /operations/abc123, client polls GET /operations/abc123 until status: "succeeded", DELETE /operations/abc123 cancels in-progress operation. Example: Azure VM creation takes 2-5 minutes, returns 202 immediately so client doesn't timeout, polls every 5-10 seconds until provisioning completes.

Optimistic concurrency: Use ETags (entity tags) for conditional requests. GET returns ETag header (e.g., ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"). PUT/PATCH/DELETE includes If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4" header. Return 412 Precondition Failed if ETag mismatch (resource changed by another client). Prevents lost updates in concurrent scenarios. Error responses: RFC 9457 Problem Details format (application/problem+json) with type (URI identifying error), title (human-readable summary), status (HTTP status code), detail (specific explanation), instance (URI identifying this occurrence). Include correlation ID in x-ms-correlation-request-id header for support troubleshooting. Example: {"type": "/errors/insufficient-funds", "title": "Insufficient Funds", "status": 400, "detail": "Account balance is $50, transaction requires $100", "instance": "/account/12345/transactions/67890"}.

Rate limiting: Return RateLimit-* headers - RateLimit-Limit: 1000 (total allowed), RateLimit-Remaining: 247 (requests left), RateLimit-Reset: 1704974400 (Unix timestamp when resets). 429 Too Many Requests with Retry-After: 60 (seconds until retry). CORS support: Implement proper Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers for browser clients. HATEOAS links: Include hypermedia links for discoverability ({"_links": {"self": "/users/123", "orders": "/users/123/orders"}}). API lifecycle: Deprecation warnings with Sunset header (RFC 8594) indicating removal date, changelog documentation, sunset timeline (announce 6-12 months before removal). Tools: Azure API Management for gateway, OpenAPI 3.1 spec, Swagger UI, Azure SDKs (auto-generated from OpenAPI). Microsoft prescriptive guidance ensures consistency across all Azure services.