Good API design: REST vs GraphQL vs RPC, versioning, pagination

Three ways to see it

1. 1

   REST is one style of API. The other two you will meet in 2026 are GraphQL and RPC, or its modern incarnation gRPC. REST exposes resources at URLs and uses HTTP verbs. GraphQL exposes one endpoint and lets the caller send a query asking for exactly the fields they want, no more and no less. gRPC exposes functions, with strongly typed inputs and outputs, optimised for server-to-server speed inside a data centre. Each style has a home. REST for public-facing, broadly consumed APIs. GraphQL for mobile and web apps with many small UI fragments. gRPC for high-traffic internal microservices.

2. 2

   Pakistani context. NADRA, FBR, SECP, and PTA all publish REST APIs, because REST is the lingua franca of integration partners (banks, telcos, vendors) and it works over the boring HTTP everyone already trusts. Easypaisa and JazzCash use GraphQL inside their mobile apps for screens that need to show the user's balance, last five transactions, and three promo banners in one paint. State Bank's PRISM uses ISO 20022 messages over secure channels, which is its own world but RPC-flavoured. As a manager, you mostly care about REST. As a CTO, you have to know when GraphQL or gRPC actually pays off.

3. 3

   Versioning is the discipline of changing an API without breaking every consumer. Two healthy patterns dominate. URL versioning bakes the version into the path: /v1/taxpayers, /v2/taxpayers. Header versioning carries the version in a custom header. The choice is less important than the rule: never make a breaking change to an existing version. If you need to remove a field, add a new version. If you need to rename a field, add the new name in the same version and keep the old name as an alias. Deprecate loudly, in the response headers and in the docs. Sunset on a published timeline, not on a Friday afternoon.

The why-tree

Try this with Claude

AI-edge prompt to try with Claude or ChatGPT: 'I am drafting a public REST API for SECP's company registry. Write an OpenAPI 3.0 spec with endpoints for company search, filing history, director list. Use cursor-based pagination, ISO 8601 dates, structured error objects, URL versioning at /v1. Include rate limit headers. Add Urdu localised error messages.' Read the YAML, paste into editor.swagger.io, see if it renders.