REST API design with versioning and OpenAPI documentation

Design a complete REST API for [PROJECT NAME], a [TYPE: SaaS/marketplace/fintech] built with [NODE.JS + EXPRESS/FASTIFY/NESTJS] and [POSTGRESQL/MYSQL].\\\\\\\\n\\\\\\\\n**Context:**\\\\\\\\n- Main resources: [LIST OF ENTITIES: users, orders, products, etc.]\\\\\\\\n- Consumers: [FRONTEND SPA, MOBILE APP, EXTERNAL PARTNERS]\\\\\\\\n- Expected volume: [NUMBER] requests/second\\\\\\\\n- Authentication: [JWT/API KEY/OAUTH2]\\\\\\\\n\\\\\\\\n**1) Conventions and Naming:**\\\\\\\\n- URL structure (plural, kebab-case, hierarchy)\\\\\\\\n- HTTP methods per operation (GET, POST, PUT, PATCH, DELETE)\\\\\\\\n- Standardized status codes (success, client error, server error)\\\\\\\\n- Standard response format: \\\\\\\\\\\\\\\\\\\\\\\`{ data, meta, errors }\\\\\\\\\\\\\\\\\\\\\\\`\\\\\\\\n- Error envelope: \\\\\\\\\\\\\\\\\\\\\\\`{ code, message, details, timestamp }\\\\\\\\\\\\\\\\\\\\\\\`\\\\\\\\n\\\\\\\\n**2) Versioning:**\\\\\\\\n- Strategy: URL path (/v1/) vs. header vs. query param — recommend and justify\\\\\\\\n- Deprecation policy (timeline, warning headers)\\\\\\\\n- Backward compatibility maintenance\\\\\\\\n\\\\\\\\n**3) Pagination, Filtering, and Sorting:**\\\\\\\\n- Cursor-based pagination (for feeds) vs. offset (for tables)\\\\\\\\n- Filters via query params: \\\\\\\\\\\\\\\\\\\\\\\`?status=active&created_after=2026-01-01\\\\\\\\\\\\\\\\\\\\\\\`\\\\\\\\n- Sorting: \\\\\\\\\\\\\\\\\\\\\\\`?sort=-created_at,name\\\\\\\\\\\\\\\\\\\\\\\`\\\\\\\\n- Partial fields: \\\\\\\\\\\\\\\\\\\\\\\`?fields=id,name,email\\\\\\\\\\\\\\\\\\\\\\\`\\\\\\\\n- Meta response: \\\\\\\\\\\\\\\\\\\\\\\`{ total, page, per_page, next_cursor }\\\\\\\\\\\\\\\\\\\\\\\`\\\\\\\\n\\\\\\\\n**4) Authentication and Authorization:**\\\\\\\\n- JWT authentication flow (access + refresh tokens)\\\\\\\\n- Role-based authorization middleware (admin, user, partner)\\\\\\\\n- Rate limiting by API key (tiers: free, pro, enterprise)\\\\\\\\n- CORS configuration per environment\\\\\\\\n\\\\\\\\n**5) OpenAPI 3.1 Documentation:**\\\\\\\\n- Schema for each endpoint with examples\\\\\\\\n- Typed request/response models\\\\\\\\n- Documented authentication (securitySchemes)\\\\\\\\n- Auto-generation with Swagger UI\\\\\\\\n- Exported Postman collection\\\\\\\\n\\\\\\\\nInclude complete examples for [MAIN RESOURCE] endpoints (CRUD + search + custom actions).