In GraphQL, the client describes the shape of the data it wants and gets back data in that shape. The GraphQL specification calls it "a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions," and the graphql.org learning pages show how a request works in practice.

One request, start to finish

The specification's own first example is small. A client sends this:

{
  user(id: 4) {
    name
  }
}

The response comes back as JSON with the same nesting: a user object holding a name. GraphQL's queries page puts it this way: "the result has the same shape as the query. This is essential to GraphQL, because you always get back what you expect, and the server knows exactly what fields the client is asking for."

Where does the request go? The page on serving GraphQL over HTTP says "a GraphQL server operates on a single URL/endpoint, usually /graphql , and all GraphQL requests for a given service should be directed to this endpoint." The same page says requests "are sent using the POST HTTP method, but query operations may also be sent using the GET method."

Results arrive under a top-level data key, and "If the request raised any errors, there will be information about what went wrong on a top-level errors key."

The queries page says "GraphQL supports three main operation types—queries, mutations, and subscriptions." The mutations page covers how to "modify data with a GraphQL server", and the subscriptions page describes how to "receive real-time updates via long-lived requests."

Where the difference from REST shows up

The queries page draws the comparison itself: "GraphQL queries can traverse related objects and their fields, letting clients fetch lots of related data in one request, instead of making several roundtrips as one would need in a classic REST architecture."

The specification frames the same idea as a design principle it calls "Client-specified response". Through its type system, a GraphQL service "publishes the capabilities that its clients are allowed to consume. It is the client that is responsible for specifying exactly how it will consume those published capabilities."

For an integration, that means one call can ask for an account, its contacts and each contact's latest activity, with only the fields the integration uses. Whether your product's schema actually links those objects is a product question. The REST side of that comparison is in how to explain APIs to buyers.

The schema is the contract

"Every GraphQL service defines a set of types that completely describe the set of possible data we can query on that service," says the schema page. "Then, when requests come in, they are validated and executed against that schema."

The specification is also clear about what GraphQL leaves to the service. It is "not a programming language capable of arbitrary computation," and the spec goes on to say that "GraphQL does not mandate a particular programming language or storage system." So GraphQL itself says nothing about the language or database behind your API.

Clients can ask a schema about itself. The introspection page describes "special kinds of queries that allow you to learn about a GraphQL API's schema," which "also help power GraphQL development tools." It also notes: "Disabling introspection in production is common in order to reduce the API's attack surface." If a buyer's developer expects to explore your schema with a tool, they need to know whether introspection is on for them, or whether you publish the schema another way.

Security questions that follow

Because every request goes to one endpoint, a security reviewer may ask where access checks happen. The HTTP page answers for GraphQL in general: "GraphQL should be placed after all authentication middleware so that you have access to the same session and user information you would in your other HTTP endpoint handlers." It continues: "field-level authorization should be enforced by the business logic called from resolvers."

Field-level authorization means two users can send the same query and get different fields back, depending on what each is allowed to see. If your product has roles, a reviewer can ask which roles see which fields, and the answer builds on how roles are explained to buyers.

A single flexible query can also be expensive to run. The introspection page lists protections a GraphQL API may use: "operation safe-listing (or a range of alternative protections, such as depth-limiting, breadth-limiting, alias limits, cycle rejection, cost analysis, etc.), execution timeouts, and more." A buyer used to REST rate limits that count requests may ask how your API limits query cost instead.

A hypothetical evaluation

Picture a hypothetical buyer, Northwind, whose developer reads that your API offers GraphQL and writes back asking whether everything goes through one endpoint and how they can see the schema. A follow-up asks how large queries are limited.

One endpoint is the general case on graphql.org, where a server "operates on a single URL/endpoint". Schema access depends on whether introspection is enabled for customers or a schema file is published. Query limits depend on which of the protections listed above your API uses; the introspection page names depth-limiting and cost analysis among them.