Platform APIs
REST, GraphQL, and gRPC API design patterns used across Auralytix-built platforms.
Picking a protocol by consumer, not by trend
REST remains the right default for public, cacheable, resource-oriented APIs — it's the easiest for third-party integrators to reason about. GraphQL earns its complexity when a frontend needs to compose data from many resources per view and over-fetching REST would otherwise cause a proliferation of bespoke endpoints. gRPC is the right choice for internal service-to-service calls where latency and strong typing matter more than human readability.
Versioning without breaking integrators
We version in the URL path for REST (`/v1/...`) rather than headers, since it's discoverable and impossible to get wrong by accident. Additive changes (new optional fields) ship without a version bump; anything that changes existing field meaning or removes a field gets a new version with a documented deprecation window for the old one.
Consistency conventions that save integration time
Every endpoint returns errors in the same shape (code, message, and a machine-readable `details` object), pagination uses the same cursor convention everywhere, and every list endpoint supports the same filter/sort query parameter pattern. None of this is exciting, but it's what makes an API fast for a third-party developer to integrate against without reading every endpoint's docs individually.
Working through something like this?
Get a scored blueprint in the Architecture Lab, or talk it through with the Architect Assistant first.