Api

GraphQL and REST are both popular API design approaches. Here’s when to use each. REST API Overview REST (Representational State Transfer) uses HTTP methods to interact with resources. Characteristics Resource-based: URLs represent resources HTTP methods: GET, POST, PUT, DELETE Stateless: Each request is independent Multiple endpoints: Different URLs for different resources Example GET /api/users GET /api/users/123 POST /api/users PUT /api/users/123 DELETE /api/users/123 GraphQL Overview GraphQL is a query language and runtime for APIs. ...

Good API design is crucial for developer experience and system success. Here are best practices for designing RESTful APIs. 1. Use RESTful Conventions Resource-Based URLs # Good: Resource-based GET /api/users GET /api/users/123 POST /api/users PUT /api/users/123 DELETE /api/users/123 # Bad: Action-based GET /api/getUsers POST /api/createUser POST /api/deleteUser HTTP Methods GET: Retrieve resources POST: Create resources PUT: Update entire resource PATCH: Partial update DELETE: Remove resource 2. Consistent Naming Use Plural Nouns # Good GET /api/users GET /api/orders GET /api/products # Bad GET /api/user GET /api/order GET /api/product Use kebab-case or camelCase # Good: Consistent GET /api/user-profiles GET /api/orderItems # Bad: Mixed GET /api/user_profiles GET /api/order-items 3. Version Your API URL Versioning GET /api/v1/users GET /api/v2/users Header Versioning GET /api/users Accept: application/vnd.api+json;version=2 4. Use Proper HTTP Status Codes Success Codes 200 OK # Successful GET, PUT, PATCH 201 Created # Successful POST 204 No Content # Successful DELETE Client Error Codes 400 Bad Request # Invalid request 401 Unauthorized # Authentication required 403 Forbidden # Not authorized 404 Not Found # Resource doesn't exist 409 Conflict # Resource conflict 422 Unprocessable # Validation errors Server Error Codes 500 Internal Server Error 502 Bad Gateway 503 Service Unavailable 5. Consistent Response Format Standard Response Structure { "data": { "id": "123", "type": "user", "attributes": { "name": "John Doe", "email": "[email protected]" } }, "meta": { "timestamp": "2025-12-10T10:00:00Z" } } Error Response Format { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "details": [ { "field": "email", "message": "Invalid email format" } ] } } 6. Pagination Cursor-Based Pagination GET /api/users?cursor=eyJpZCI6IjEyMyJ9&limit=20 Response: { "data": [...], "pagination": { "cursor": "eyJpZCI6IjE0MyJ9", "has_more": true } } Offset-Based Pagination GET /api/users?page=1&limit=20 Response: { "data": [...], "pagination": { "page": 1, "limit": 20, "total": 100, "total_pages": 5 } } 7. Filtering and Sorting Filtering GET /api/users?status=active&role=admin GET /api/orders?created_after=2024-01-01&created_before=2024-12-31 Sorting GET /api/users?sort=name,email&order=asc,desc GET /api/users?sort=-created_at # Descending 8. Field Selection Sparse Fieldsets GET /api/users?fields=id,name,email GET /api/users/123?fields=id,name Include Related Resources GET /api/users/123?include=orders,profile 9. Rate Limiting Headers X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1609459200 Response HTTP/1.1 429 Too Many Requests Retry-After: 60 10. Authentication and Authorization Use Standard Methods # Bearer token Authorization: Bearer <token> # API key X-API-Key: <key> Return Clear Errors { "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired token" } } 11. Documentation OpenAPI/Swagger openapi: 3.0.0 info: title: User API version: 1.0.0 paths: /users: get: summary: List users responses: '200': description: Success Interactive Documentation Swagger UI: Visual API documentation Postman: API testing and docs Redoc: Beautiful API docs 12. Error Handling Consistent Error Format { "error": { "code": "RESOURCE_NOT_FOUND", "message": "User with ID 123 not found", "request_id": "req_abc123" } } Validation Errors { "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "errors": [ { "field": "email", "message": "Invalid email format", "code": "INVALID_FORMAT" } ] } } 13. Caching Cache Headers Cache-Control: public, max-age=3600 ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4" Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT Conditional Requests GET /api/users/123 If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4" # 304 Not Modified if unchanged 14. Security Best Practices Use HTTPS Always use HTTPS in production. ...

Approaches Token bucket for burst+steady control; sliding window for fairness. Enforce at edge (gateway/ingress) plus app-level for per-tenant safety. Spring implementation Use filters/interceptors with Redis/Lua for atomic buckets. Key by tenant/user/IP; return 429 with Retry-After. Expose metrics per key and rule; alert on near-capacity. Considerations Separate auth failures from rate limits; avoid blocking login endpoints too aggressively. Keep rule configs dynamic; hot-reload from config store. Combine with circuit breakers/timeouts for upstream dependencies. Checklist Edge and app-level limits defined. Redis-based atomic counters/buckets with TTL. Metrics + logs for limit decisions; alerts in place.

Identity & access Enforce strong auth (OIDC/JWT); short-lived tokens + refresh; audience/issuer checks. Fine-grained authz (RBAC/ABAC); deny-by-default; rate-limit per identity. Input & data Validate/normalize input; reject oversized bodies; JSON schema where possible. Output encode; avoid reflecting raw user data; paginate results. Store secrets in vault/KMS; rotate keys; never log secrets/tokens. Transport & headers TLS everywhere; HSTS; modern ciphers. Security headers: Content-Security-Policy, X-Content-Type-Options=nosniff, X-Frame-Options=DENY, Referrer-Policy. Abuse protection Rate limit + burst control; CAPTCHA/step-up for sensitive actions. Bot detection where relevant; geo/IP allow/deny for admin surfaces. Observability Structured audit logs with identity, action, resource, result; avoid PII spill. Alerts on auth failures, unusual rate spikes, and 5xx anomalies. Checklist AuthZ enforced; least privilege. Input validated; size limits set. TLS + security headers applied. Rate limits + abuse controls configured. Secrets vaulted and rotated.

Designing a REST API that is intuitive, maintainable, and scalable requires following established best practices. Here’s a comprehensive guide. 1. Use Nouns, Not Verbs Good GET /users GET /users/123 POST /users PUT /users/123 DELETE /users/123 Bad GET /getUsers GET /getUserById POST /createUser PUT /updateUser DELETE /deleteUser 2. Use Plural Nouns Good GET /users GET /orders GET /products Bad GET /user GET /order GET /product 3. Use HTTP Methods Correctly // GET - Retrieve resources GET /users // Get all users GET /users/123 // Get specific user // POST - Create new resources POST /users // Create new user // PUT - Update entire resource PUT /users/123 // Replace user // PATCH - Partial update PATCH /users/123 // Update specific fields // DELETE - Remove resources DELETE /users/123 // Delete user 4. Use Proper HTTP Status Codes // Success 200 OK // Successful GET, PUT, PATCH 201 Created // Successful POST 204 No Content // Successful DELETE // Client Errors 400 Bad Request // Invalid request 401 Unauthorized // Authentication required 403 Forbidden // Insufficient permissions 404 Not Found // Resource doesn't exist 409 Conflict // Resource conflict // Server Errors 500 Internal Server Error 503 Service Unavailable 5. Consistent Response Format { "data": { "id": 123, "name": "John Doe", "email": "[email protected]" }, "meta": { "timestamp": "2024-11-15T10:00:00Z" } } Error Response Format { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input data", "details": [ { "field": "email", "message": "Invalid email format" } ] } } 6. Versioning URL Versioning /api/v1/users /api/v2/users Header Versioning Accept: application/vnd.api+json;version=1 7. Filtering, Sorting, Pagination GET /users?page=1&limit=20 GET /users?sort=name&order=asc GET /users?status=active&role=admin GET /users?search=john 8. Nested Resources GET /users/123/posts POST /users/123/posts GET /users/123/posts/456 PUT /users/123/posts/456 DELETE /users/123/posts/456 9. Use HTTPS Always use HTTPS in production to encrypt data in transit. ...

Axum is a modern web framework for Rust. Here’s how to build your first API. Setup [dependencies] axum = "0.7" tokio = { version = "1", features = ["full"] } serde = { version = "1.0", features = ["derive"] } Basic Server use axum::{Router, routing::get, Json}; #[tokio::main] async fn main() { let app = Router::new() .route("/", get(handler)); axum::Server::bind(&"0.0.0.0:3000".parse().unwrap()) .serve(app.into_make_service()) .await .unwrap(); } async fn handler() -> Json<serde_json::Value> { Json(serde_json::json!({"message": "Hello, World!"})) } Routes let app = Router::new() .route("/users", get(get_users)) .route("/users/:id", get(get_user)); JSON Handling use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize)] struct User { id: u32, name: String, } async fn create_user(Json(user): Json<User>) -> Json<User> { Json(user) } Best Practices Use type-safe routing Handle errors properly Use middleware Test endpoints Document APIs Conclusion Build fast and safe APIs with Rust and Axum! 🦀