API Design Basics: REST vs GraphQL Explained

An API (application programming interface) is a defined way for one piece of software to ask another for data or to perform an action. REST and GraphQL are two common styles. REST exposes many URLs, each representing a resource (such as /customers/42), and uses standard HTTP methods like GET and POST. GraphQL exposes a single endpoint where the client sends a query describing exactly which fields it wants. Choose REST for straightforward, resource-oriented systems and broad compatibility; consider GraphQL when many different clients need flexible shapes of data from the same back end. Either can be done well or badly, so the design principles below matter more than the label.

What an API does for your business

APIs connect things: your website to your database, your mobile app to your back end, your accounting package to your order system, your system to a partner's. A well-designed API makes integrations quick to build and cheap to maintain. A poor one becomes a source of bugs and bottlenecks that every future project has to work around. If you are planning software, API design belongs in the early architecture discussion, as part of planning the project.

How REST works

REST (representational state transfer) is an architectural style built on how the web already works. Core ideas:

• Resources have URLs. For example, /orders for the collection and /orders/1001 for one order.
• HTTP methods carry the intent. GET reads, POST creates, PUT or PATCH updates, DELETE removes.
• Standard status codes report results. 200 OK, 201 Created, 400 Bad Request, 401 Unauthorised, 404 Not Found, 500 Server Error.
• Stateless. Each request contains everything the server needs, such as an authentication token.
• Usually JSON as the data format.

GET /api/v1/orders/1001

200 OK
{
  "id": 1001,
  "status": "shipped",
  "customerId": 42,
  "total": 180.00
}

Strengths: simple to understand, works with ordinary tools and browsers, easy to cache, widely supported. Weaknesses: clients may need several requests to assemble a screen (under-fetching), or receive more data than they need (over-fetching).

How GraphQL works

GraphQL, originally developed at Facebook and now maintained as an open specification, uses one endpoint and a typed schema. The client sends a query describing the exact shape it wants, and the server returns that and nothing else.

query {
  order(id: 1001) {
    status
    total
    customer {
      name
      email
    }
  }
}

One request returns the order and the related customer details. Strengths: clients ask for exactly what they need, fewer round trips, a self-describing schema that helps tooling and documentation. Weaknesses: more complex to implement and secure, harder to cache with standard HTTP tools, and it is easy to write queries that put heavy load on the server unless limits are applied.

REST vs GraphQL at a glance

Aspect	REST	GraphQL
Endpoints	Many, one per resource	Usually one
Data shape	Fixed by the server	Chosen by the client
Requests per screen	Sometimes several	Often one
Caching	Straightforward with HTTP caching	Needs more care
Learning curve	Gentle	Steeper
Tooling and familiarity	Very widespread	Mature but narrower
Best for	Simple CRUD systems, public and partner APIs, quick integrations	Complex data relationships, multiple client types such as web and mobile

Which should you choose?

• Choose REST if your data maps neatly to resources, your team is small, you expect third parties to integrate, or you want the simplest thing that works.
• Choose GraphQL if you have several clients with different data needs, deeply related data, or a front-end team that needs to move quickly without waiting for new endpoints.
• Use both if it is sensible. Some systems expose REST for partners and GraphQL for their own front end.

If you are unsure, start with REST. It is easier to add GraphQL later than to untangle an over-engineered start.

Design basics that apply to any API

Be consistent

Use the same naming style, date format, error structure and pagination approach everywhere. Consistency is what makes an API feel easy to learn.

Name things after the business

Use nouns for resources (customers, invoices) and words your users use. Avoid leaking internal database names.

Plan for errors

Return meaningful status codes and clear messages with a stable error format, so a client developer knows what went wrong and what to fix.

Paginate and filter

Never return unlimited lists. Offer paging, sorting and filtering so responses stay small and fast.

Version and evolve carefully

Prefer additive changes (new fields, new endpoints) that do not break existing clients. When breaking changes are unavoidable, introduce a new version and give clients time to move.

Document it

For REST, the OpenAPI specification is the common way to describe an API in a machine-readable form. GraphQL schemas are self-describing. Good documentation with examples reduces support questions.

Security checklist

• Authenticate every request (for example with OAuth 2.0 tokens) and always use HTTPS.
• Check authorisation for each resource, not only at login: can this user see this particular record?
• Validate and sanitise all input on the server.
• Apply rate limiting to blunt abuse and accidental overload.
• Do not expose more data than needed in responses.
• For GraphQL, limit query depth and complexity.
• Log access for investigation, taking care not to log secrets or sensitive personal data.
• Review against the OWASP API Security guidance.

Common mistakes

• Designing around the database, not the use cases. The API should serve what clients need to do.
• Inconsistent behaviour. One endpoint returns errors as text, another as JSON; one uses dates in one format, another differently.
• Breaking changes without warning. Partners who depend on you will not be pleased.
• Skipping authorisation checks. Logged-in does not mean allowed to see everything.
• Choosing GraphQL for fashion. If a handful of REST endpoints do the job, keep it simple.
• No documentation or tests. Undocumented APIs cost more in support than the time saved. Include API checks in your test suite.

An example of good and poor design

Consider a request to list a customer's invoices. A poorly designed API might use an endpoint like /getInvoicesForCustomer?id=42, return every invoice ever created in one huge response, and report failures with HTTP 200 and a text message saying "error". A better design uses /customers/42/invoices, accepts parameters such as page, pageSize, status and from or to dates, returns a predictable JSON structure with the total count, and uses proper status codes and a consistent error object that includes a short code and a readable message.

The second version takes slightly longer to design but saves every consumer of the API time, whether that is your own mobile app, a partner or a developer joining the team in a year's time. It also makes the API easier to test, monitor and secure, because behaviour is uniform and predictable. When you review a proposal, ask to see example requests and responses for the two or three most important operations. They reveal the quality of the design far better than a diagram does.

Designing APIs with a development partner

If your project connects several systems, ask your developers to show you the proposed API design and the reasoning, ideally before building. It is far cheaper to adjust a design than a live integration. Soch Tech builds web, mobile and desktop software that connects to databases, cloud systems and third-party APIs; to discuss yours, see our custom software development service.