REST API design for a B2B SaaS: nested vs flat structure, versioning, and docs.

[DanielHD]

I'm a backend developer tasked with designing a new REST API for a B2B SaaS platform that will expose complex, hierarchical data models to third-party integrators. I'm struggling with some fundamental design decisions, particularly around nested resources versus a flatter structure with more query parameters. For experienced API architects, what are your guiding principles for versioning, error handling, and pagination in a public-facing API that needs to remain stable for years? How do you effectively document hypermedia controls and relationship links without overwhelming consumers, and are tools like OpenAPI specs with code generation worth the initial overhead? What's the best way to handle partial updates and concurrency control for resources that might be modified by multiple clients simultaneously?

[Kyle28]

In practice, start simple with a flat core API and add nested relationships on an as-needed basis. Use expansion mechanisms rather than deeply nesting resources: a query parameter like expand/include to fetch related data when the client wants it, and keep URIs stable. Design around resource identity first, then think about how clients will traverse it (think hypermedia-lite rather than full-on hypermedia). Also define clear field selection with a fields parameter to trim payloads.

[Sophia.R]

Versioning carefully: put the version in the URL (v1, v2) and publish a public deprecation schedule. Keep old versions alive for a reasonable window, and use migration guides and adapters so you can evolve endpoints without breaking existing clients. A small change log per version plus a formal sunset plan helps keep customers from being blindsided.

[Edward_R]

Error handling you should own: return a structured problem details payload per RFC 7807. Include fields like type, title, status, detail, and instance, plus an optional extensions object for codes or details. Map common cases to HTTP status codes (400 for validation, 404 for not found, 409 for conflicts, 429 for rate limits, 500 for server errors). Provide a standard set of example error responses for new endpoints.

[Aurora_J]

Pagination: prefer cursor-based pagination for large datasets; return a next_cursor or page_token and a has_more flag, along with a small meta object. For simple lists, you can still use limit/offset but avoid large offset values. Always include total counts only if query cost is acceptable. Helpful practice: include Link headers with next/prev URLs to aid navigation.

[SamuelPW]

Hypermedia and documentation: a light touch can help folks discover relationships, but don’t force it if your API is large and performance-sensitive. If you embrace hypermedia, choose a consistent approach like HAL or JSON:API and document it in the OpenAPI spec with explicit links sections. Otherwise, keep your standard endpoints clean and use explicit, stable links in responses for discoverability.

[MichaelCJ]

OpenAPI and tooling: adopting OpenAPI is worth it if you have multiple teams consuming the API. A contract-first approach (design the spec first, then generate server stubs) can reduce drift and improve client parity. Tools like openapi-generator, Swagger UI, and Redoc can boost adoption. Be mindful of drift between docs and implementation and treat codegen as a productivity aid, not a mandate.

[NathanS]

Partial updates and concurrency: prefer PATCH with JSON Patch (RFC 6902) or JSON Merge Patch for smaller changes. Use optimistic concurrency control via ETag/If-Match so clients can detect conflicts. Maintain a separate version field or revision tag on resources and fail with 409 on mismatches, giving clients a clean path to retry after resolving conflicts. Consider also Last-Modified-based checks as a lighter alternative if your clients don’t want to manage ETags.