Docs / Writing diagrams

Requests and responses

Payloads are what make a Volley diagram useful to the person who has to build or debug the integration.

A payload is the data a message carries. Every message can have two:

• an input, written in:, for what the sender sends, such as a request body, query parameters or headers;
• an output, written out:, for what comes back, such as a response body or a status line with headers.

Payloads do not clutter the drawing. Each arrow shows a small in or out chip with the payload's title, and a click on the arrow shows the whole thing. Turn on Show payloads under the diagram to draw every payload inline instead.

#Writing a payload

Put in: or out: on the line right after the message, followed by a title. The body is every line after that until the next statement:

volley

title: A payload on each side
App -> Auth Server: POST /token
in: Token request
  grant_type: authorization_code
  code: SplxlOBeZQQYbYS6WxSbIA
out: Token response
```json
{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 3600 }
```

• The title is optional but helps readers: in: Token request reads better than a bare in:.
• Indentation in the body is removed, so you can indent it for readability.
• If a message has both, write in: first, then out:.
• An in: or out: that is not directly after a message is an error: "in:" must follow a message.
• A second in: on the same message replaces the first, with a warning.

#Output on the request or on the reply

You can put the response on the request itself, as above, or on the dashed reply arrow:

App -> Auth Server: POST /token
in: Token request
  grant_type: client_credentials

Auth Server --> App: 200 OK
out: Token
  access_token: eyJhbGciOi...

Both are fine. Putting out: on the reply shows the status code on its own arrow, and lets each branch of an if carry a different response. When a request has no output of its own, the inspector shows its reply's output under it, so readers find the response either way.

#Formats

Volley recognises the format of a body and shows it as a table of fields as well as the raw text.

A fence with any other tag, such as sql or xml, is shown as text.

#JSON

Client -> API: POST /orders
in: Order
```json
{ "sku": "BOOK-1", "quantity": 2, "gift": false }
```

One-line JSON is pretty-printed for you in the raw view.

#Form bodies

App -> Auth Server: POST /token
in: Token request
```form
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=volley-web
```

#Parameters and headers

Plain key: value lines need no fence at all, which makes them the quickest way to write query parameters, form fields and headers:

Service -> API: GET /invoices
in: Query
  status: open
  limit: 50

Tag the fence headers when the lines are HTTP headers. It reads the same way and tells readers what they are looking at.

#Raw HTTP

Use http when the status line and headers matter, such as a redirect or a response with caching headers:

App --> Browser: 302 Found
out: Redirect
```http
HTTP/1.1 302 Found
Location: https://auth.example.com/authorize?response_type=code&client_id=volley-web
Cache-Control: no-store
```

#Text

Anything else, such as SQL, a log line, an event description or XML:

Shop -> Database: Save the order
in: Query
```text
INSERT INTO orders (sku, quantity) VALUES ($1, $2)
```

#When to fence a body

An unfenced body ends at the first line that reads as a statement. That is usually what you want, but it can surprise you when a field is named like a keyword. These keys start a statement: title, order, note, in, out, if, else, end and group. A line such as title: Refund inside an unfenced body closes the body and sets the diagram title instead.

Fence the body to keep every line in it:

Shop -> CMS: Create a page
in: Page
```params
title: Refund policy
order: 3
```

Inside a fence, nothing is a statement and // is not a comment. Any body can be fenced, and fencing is never wrong.

#Secrets and redaction

Diagrams get shared, so Volley helps you keep real secrets out of them.

• Mark a value as redacted. Write <redacted>, [redacted] or *** as the value. Volley shows it as redacted instead of as text.
• Sensitive keys are labelled. Keys that look secret, such as password, client_secret, access_token, api_key, authorization, cookie, session and code_verifier, are tagged as example values in the inspector, so readers know the value shown is not real. Names that only describe a secret, like token_type, expires_in or token_endpoint, are not tagged.
• Imports redact for you. When you import a HAR file, capture a webhook or receive a recording, tokens, cookies, passwords and API keys are replaced with <redacted> before they become part of the diagram.

Service -> Auth Server: POST /oauth2/token
in: Client credentials
  grant_type: client_credentials
  client_id: billing-worker
  client_secret: <redacted>

#Inspecting payloads

Click an arrow to open the inspector. For each payload you get:

• an Input or Output tag, the format, and the title;
• a Fields tab with a Name and Value table, where redacted values and example values are tagged;
• a Raw tab with the body exactly as written.

See Reading a diagram for everything else the inspector shows.