Three other shapes
Tuesday morning of story week 5. Devon pinged me Friday. Come by Tuesday morning, I want to whiteboard three shapes we passed on. I find him at the small whiteboard near his desk. Four sketches up: REST, SOAP, GraphQL, gRPC. Under SOAP he has written “1998” and below that, “still in production at your bank.”
He turns. “Last week was one argument. Today is three.”
Last week Asha wanted POST /search and Devon walked me through the verb. This morning he wants to show me the three shapes Greenfield could have shipped instead. Today you need to know which shape Greenfield is, because you start the advanced filter assignment this week, and a word on the doc page only means what it means once you know the shape.
Today you will leave with
- How to recognize four API shapes by their request envelopes.
- What each shape commits to in one sentence.
- What the docs’ first page owes the reader, shape by shape.
Every shape is a set of commitments
Every shape is a set of commitments. An API picks one. Each shape commits the server, the client, the cache, and the doc page to a particular way of working. The shape is the contract.
Take SOAP first. SOAP is XML in an envelope. Each call sends an envelope with a header and a body. The SOAPAction header tells the server which operation to run. The contract is a WSDL file. The cache stays out of it (every call is a POST to one URL). If Greenfield had shipped SOAP, Asha’s email would have been “send us the WSDL” and Marginalia would have generated a client from it.
GraphQL
next. GraphQL is one endpoint, usually POST /graphql, with the query in the body. The contract is the schema. The cache stays out of it by default (every call is a POST). If Greenfield had shipped GraphQL, Asha would have asked for the schema and her code would have written a query for the fields she needed.
gRPC
last. gRPC is binary over HTTP/2. The contract is a .proto file and the wire format is Protocol Buffers. The client is generated from the proto. The cost is HTTP/2 support all the way down: browsers without grpc-web cannot talk to it, proxies that do not speak HTTP/2 drop the connection, and the cache cannot read it. If Greenfield had shipped gRPC, Asha would have asked for the proto file and Marginalia would have built the generated client into the Atlas service.
Two shapes Devon does not sketch this morning. WebSocket is a connection model, not a request shape, and gets its own lesson in Module 6. The older RPC family that gRPC modernized is more concept than working choice today.
REST is the shape Greenfield ships. REST commits to HTTP verbs, URLs, and a body that is usually JSON. The cache holds GETs by default. The schema is optional. Greenfield ships OpenAPI alongside. REST’s commitments happen to fit a public catalog API for an open web. That is why Greenfield is REST.
sequenceDiagram participant Atlas participant API as Greenfield GraphQL Atlas->>API: POST /graphql Note over Atlas,API: Body carries a GraphQL query API-->>Atlas: 200 with data matching the query Note over API: One URL for everything. The query in the body says what to do.
Look at the diagram. GraphQL puts the question in the body. The body carries query { books(q: "mystery") { title } }. One endpoint, one POST, the query says what to do. The cache stays out of it.
Name the shape on page one
Every API doc has a first page. Its first sentence tells the reader what shape they are reading. Greenfield’s reads “Greenfield is a REST API.” Three words. Every reader after that sentence knows what to expect: a list of resources, HTTP verbs, JSON, and a cache that holds GETs.
The shape decides what the first page owes the reader.
A REST doc owes a resource list with verbs and paths, a base URL, an auth section, and one sample per resource that shows a successful call. A GraphQL doc owes a schema overview, a list of queries and mutations at the top level, and a playground link so the reader can run a query without writing code. A gRPC doc owes the proto file, the service list, and a code sample per supported language because the client is generated, not written. A SOAP doc owes the WSDL URL, an envelope template, and a list of operations the WSDL declares.
Greenfield’s first page does the REST owing list. It opens with “Greenfield is a REST API,” lists the six resources, and shows one GET example with a JSON response:
$ curl -H "Authorization: Bearer $GF_TOKEN" \
"https://api.greenfield.lib/v1/books?q=mystery"
The page does the recognition work so the reader does not have to do it.
Devon’s whiteboard appears below as a diagram. Four shapes, four request envelopes, one cell per shape. The REST cell is the actual shape Greenfield ships. The other three are counterfactual. Hover or tap a shape to read what Asha’s email to Greenfield would have looked like in that shape. The hover text is the same content as the prose above, expressed as a short counterfactual. The prose and the hover are interchangeable.
The recognition pattern is small. Read the first sentence of the docs. Look at the request envelope of one endpoint. You have placed the API. Once you have placed it, every subsequent decision (which page to write, which sample to ship, which header to call out) follows the shape’s owing list.
Words you can drop in standups now
SOAP . Use this when someone says “the integration is SOAP” and you want to nod and ask “do you have the WSDL.”
GraphQL . Use this when someone says “they have a GraphQL endpoint” and you want to know what to ask for next: the schema.
gRPC . Use this when someone says “the service is gRPC” and you want to ask “are we generating clients from the proto.”
request envelope . Use this when you mean “the shape of one call before the response comes back.”
AI co pilot tip
Tool: GitHub Copilot Chat (the chat panel in VS Code or your IDE of choice).
The situation. You inherit a codebase or a public schema link and you want to know which shape you are looking at before you write a single doc word. Useful when an engineer hands you a .proto file and assumes you can read it.
The prompt (paste into Copilot Chat with the schema or doc file open):
This file is part of an API. Tell me which shape this API is: REST, GraphQL, gRPC, SOAP, or something else. Quote the line that gave it away. Then in one sentence, name what that shape commits to.
What to expect back. A shape name, a quoted line, and one commitment sentence. Three lines.
What to watch for. Copilot Chat sometimes says “this could be REST or RPC over HTTP.” That hedging is the trap from block 6: an API that says REST in the marketing page but ships RPC underneath. Push back: “name the shape based on the URL patterns in this file, not the marketing.” The second pass usually picks one and defends it. If it still hedges, the file probably is RPC in a REST jacket. If Copilot paraphrases instead of quoting, ask again: “give me the literal line.”
Before you go
Pick a public API doc you remember reading. In two sentences, name the shape and name one thing the page does because of the shape.
Next week at Greenfield
Next week we open the URL the catalog actually ships under and read it left to right. Devon has feelings about every part of it.
Maya.