REST or GraphQL for a new API: how do I decide?

Short answer: REST is simpler and a safe default for most products. GraphQL shines when many different clients need flexible subsets of related data and you can afford the extra complexity.

REST

• Pros: simple mental model, works naturally with HTTP caching and status codes, broad tooling, easy to test with a browser or curl.
• Cons: over-fetching or under-fetching can require extra endpoints or multiple round trips; versioning needs thought.

GraphQL

• Pros: clients ask for exactly the fields they need, one request can span related data, a typed schema drives tooling and documentation.
• Cons: more moving parts (schema, resolvers), harder HTTP caching, the N+1 query problem unless you batch data loading, query cost control and rate limiting need design, and authorisation must be enforced per field or resolver.

Questions to ask

1. How many different clients, and do their data needs differ a lot?
2. Is the team experienced with GraphQL?
3. Do you need public caching on CDNs?
4. Is the API public (third parties) or internal?
5. How complex are the relationships between your resources?

A pragmatic approach

• Start with REST and resource-oriented endpoints, consistent errors and pagination.
• Document it with an OpenAPI specification.
• Consider GraphQL when you feel real pain: many round trips on mobile, or endless custom endpoints per screen.
• Mixing is fine: REST for simple operations and webhooks, GraphQL for a rich query layer.

Pitfalls (either style)

• Inconsistent naming and error formats.
• No pagination or rate limiting.
• Breaking changes without versioning or a deprecation window.

Pick the one your team can operate confidently; consistency matters more than the label.