architect/data-api-design

Identify core entities as nouns from the PRD, then map their relationships as one-to-one, one-to-many, or many-to-many. Render the result as a Mermaid ERD and document each table in a data dictionary with field types, constraints, defaults, and indexes.

Use plural lowercase nouns for resources, HTTP methods for actions, and URL versioning like /api/v1. Support pagination, filtering, and sorting via query parameters, and return consistent JSON envelopes with success flags and structured error codes.

UUIDs are recommended because they avoid exposing record counts and work well in distributed systems. Auto-increment integers are simpler but leak data volume and complicate multi-database merges.

RESTful suits general CRUD scenarios with simple, standard semantics. GraphQL fits complex queries and multi-client needs, while gRPC targets high-performance microservice communication. This methodology recommends RESTful unless special requirements exist.

Return a JSON object with success set to false and an error object containing a machine-readable code, a human-readable message, and optional field-level details. Use codes like VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, and CONFLICT mapped to proper HTTP status codes.