REST APIs vs GraphQL APIs in Entity Resolution

When we designed the Tilores API, we had a choice: REST or GraphQL. We chose GraphQL as the primary interface, with REST as a secondary option. Here’s why — and when REST is still the better choice.

The Entity Resolution Query Problem

Entity resolution queries are fundamentally different from typical CRUD operations. When you resolve an entity, you’re not fetching a single record by ID. You’re asking: “Given these attributes, find all matching entities and return their complete profiles with all linked records.”

The response shape varies dramatically depending on the query:

A query by email might return one entity with 3 linked records
A query by phone number might return 5 entities with 47 records total
Different consumers need different fields — the fraud team needs device IDs and IP addresses, while marketing only needs name and email

This is exactly the scenario GraphQL was designed for.

Why GraphQL Wins for Entity Resolution

1. No Over-Fetching

A REST endpoint returning a full entity profile might include 50+ fields across multiple linked records. If your application only needs the name and email, you’re transferring unnecessary data. With GraphQL, you specify exactly what you need:

[graphql] query { search(input: { email: "sarah@example.com" }) { entities { id confidence records { name email } } } }

For high-throughput applications making thousands of resolution requests per second, this reduction in payload size translates directly to lower latency and bandwidth costs.

2. Variable Response Shapes

Entity resolution responses are inherently variable. One entity might have 2 linked records, another might have 200. GraphQL handles this naturally — the schema describes the possible shape, and the client gets exactly what exists.

With REST, you’d either need multiple endpoints for different detail levels, or accept a one-size-fits-all response that’s too verbose for simple queries and too sparse for detailed ones.

3. Type Safety

GraphQL schemas provide compile-time type safety for API consumers. When you’re building a fraud detection system that depends on entity resolution, you want your IDE to tell you if you’re accessing a field that doesn’t exist — not find out at runtime in production.

4. Self-Documenting

The GraphQL schema serves as always-accurate documentation. Developers can explore the API using the built-in playground, see all available fields and types, and construct queries interactively. This dramatically reduces time-to-integration.

When REST Still Makes Sense

GraphQL isn’t always the right choice. We offer REST endpoints for these scenarios:

Webhooks and callbacks — when Tilores needs to notify your system about entity changes, a simple REST POST is cleaner than a GraphQL subscription
Bulk operations — ingesting millions of records via streaming upload is better suited to REST semantics
Simple integrations — if you just need to check whether two records match, a REST endpoint with a simple boolean response is more straightforward
Legacy system integration — some enterprise systems can only consume REST APIs

Our Approach: GraphQL Primary, REST Available

Tilores supports both GraphQL and REST. The GraphQL API is the primary interface, offering the full feature set with type safety and flexibility. REST endpoints cover the common operations for teams that prefer or require REST.

Both APIs share the same underlying resolution engine, authentication, and rate limiting. The choice of interface doesn’t affect resolution quality or performance — it’s purely about developer experience and integration requirements.

Try the GraphQL API in our interactive playground — no signup required.