API style guide

Introduction

This guide is designed for writers and contributors involved in documenting our APIs, which use both GraphQL and REST API technologies.

At Interledger, we maintain multiple repositories that encompass a variety of projects, each serving different purposes across our ecosystem. This style guide aims to provide a cohesive framework for documenting these APIs so that our docs are clear, consistent, and aligned with our standards.

GraphQL

From GraphQL.org, GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. Unlike REST APIs, where multiple endpoints are often required to retrieve and update related data, GraphQL allows clients to request exactly the data they need in a single query. This reduces the amount of data transferred over the network and minimizes the number of requests made to the server. No more over- or under-fetching of data!

For more in-depth information about GraphQL, take a look at the following resources:

• GraphQL official website
• GraphQL specification
• How To GraphQL

Documenting GraphQL examples

We’ve created a standardized format to maintain a consistent look and feel when documenting example GraphQL queries and mutations. Organize each GraphQL example into three tabs: Operation, Variables, and Response.

To create these multi-tabbed GraphQL examples, we’re using the built-in Starlight <Tabs> and <TabItem> components. Each of the examples below will show the <TabItem> tags. The full example will be wrapped in the <Tabs> tag.

Tip

Make sure you import the <Tabs> and <TabItem> components to your MDX file like so:

import { Tabs, TabItem } from '@astrojs/starlight/components'

Operation tab

• Include the query/mutation in a code block
• Specify graphql as the language for syntax highlighting
• Exclude the query/mutation name from the header

Operation tab markdown format

<TabItem label="Operation">
    ```graphql
    mutation [AnotherMutationName]($input: [AnotherInputType]!) {
      [AnotherMutationName](input: $input) {
        [AnotherResponseFields]
      }
    }
    ```
</TabItem>

Variables tab

• Provide the JSON input object in a code block
• Specify json as the language for syntax highlighting
• Below the code block, include a sentence linking to the input object documentation

Variables tab markdown format

<TabItem label="Variables">
    ```json
    {
      "input": {
        "field1": "[value]",
        "field2": "[value]",
        "field3": "[value]",
        // Add additional fields as necessary
      }
    }
    ```
    For more information about this mutation's input object, see [`[AnotherInputObjectLink]`](https://example.com).
</TabItem>

Note

Before this style guide was created, there were older GraphQL examples that, in most cases, contained a table displaying variable names and descriptions. If you are updating one of these older examples, delete this table. The input object documentation explains all of the variables and we link to that page in the Variables tab.

Response tab

• Include the JSON response in a code block
• Specify json as the language for syntax highlighting
• Provide a brief description of the expected reponse

Response tab markdown format

<TabItem label="Response">
    When the operation is successful, `[AnotherMutationName]` returns `[ExpectedResponse]`.
    ```json
    {
      data: {
        success: true
      }
    }
    ```
</TabItem>

Example of a complete GraphQL query/mutation example

Code for the complete GraphQL query/mutation example

<Tabs>
  <TabItem label="Operation">
    ```graphql
    mutation [MutationName]($input: [InputType]!) {
      [MutationName](input: $input) {
        [ResponseFields]
      }
    }
    ```
  </TabItem>
  <TabItem label="Variables">
    ```json
    {
      "input": {
        "field1": "[value]",
        "field2": "[value]",
        "field3": "[value]",
        // Add additional fields as necessary
      }
    }
    ```
    For more information about this mutation's input object, see [`[InputObjectLink]`](https://example.com).
  </TabItem>
  <TabItem label="Response">
    When the operation is successful, `[MutationName]` returns `[ExpectedResponse]`.

    ```json
    {
      data: {
        success: true
      }
    }
    ```
  </TabItem>
</Tabs>

HTML rendering of example

Operation

mutation [MutationName]($input: [InputType]!) {
  [MutationName](input: $input) {
    [ResponseFields]
  }
}

Variables

{
  "input": {
    "field1": "[value]",
    "field2": "[value]",
    "field3": "[value]",
    // Add additional fields as necessary
  }
}

For more information about this mutation’s input object, see [InputObjectLink].

Response

When the operation is successful, [MutationName] returns [ExpectedResponse].

{
  data: {
    success: true
  }
}

REST API

From restfulapi.net, a REST API (Representational State Transfer) provides a standardized way to interact with resources using predictable HTTP requests (GET, POST, PUT, DELETE). REST APIs are designed for interoperability and human readability, enabling developers to work with predictable resource paths and standardized data formats such as JSON. Each endpoint represents a resource, and responses use standard HTTP status codes to indicate success or failure.

For more in-depth information about REST APIs, take a look at the following resources:

• REST API tutorial
• MDN Docs: HTTP overview
• OpenAPI specification

In Open Payments, REST APIs expose operations such as creating incoming and outgoing payments, requesting quotes, and handling authentication. Each follows conventional HTTP request/response semantics defined in our OpenAPI specifications.

Documenting REST API examples

Our REST API examples appear in two primary contexts within the Open Payments docs:

1. SDK pages: Focused, single-operation walkthroughs showing how to call individual endpoints (for example, creating an incoming payment)
2. Guide pages: Broader workflows that combine multiple operations into real world end-to-end use cases (for example, accept a one-time payment for an online purchase)

Although both types of content reference the same underlying API endpoints, the way examples are embedded and presented differs slightly. This section explains how to structure and format these examples consistently.

Note

When writing or updating Open Payments SDK and guide pages, refer also to the Open Payments style guide. It defines higher‑level conventions such as naming, formatting, and guide structure that complement the REST‑specific example guidance below.

SDK pages

Each SDK page demonstrates how a single API operation is implemented across multiple SDKs. These examples are presented in a multi-language tabbed interface, where each programming language has its own <TabItem> component.

Like the GraphQL examples above, we’re using the built-in Starlight <Tabs> and <TabItem> components.

Tip

Make sure you import the <Tabs> and <TabItem> components to your MDX file like so:

import { Tabs, TabItem } from '@astrojs/starlight/components'

Using the tabbed interface

As stated earlier, the <Tabs> component is wrapped around all language examples, and each language is inside its own <TabItem> component. Writers do not edit the code examples themselves. Developers maintain those code snippets in their respective SDK repositories, and writers embed them into SDK pages with <ChunkedSnippet> components. It’s our role to make sure that the structure, order, and labeling of the tabs are consistent across all SDK pages.

• Maintain a consistent tab order (TypeScript/JavaScript, Rust, PHP)
• Each <TabItem> label should include both the language name and its corresponding icon when available (for example, icon="seti:javascript")
• Use <ChunkedSnippet> to import maintained code blocks directly from SDK repositories

Simplified tabbed interface - example

<Tabs>
  <TabItem label="TypeScript/JavaScript" icon="seti:javascript">
    <ChunkedSnippet source="..."  chunk="..."/>
  </TabItem>
  <TabItem label="Rust" icon="seti:rust">
    <ChunkedSnippet source="..."  chunk="..."/>
  </TabItem>
  <TabItem label="PHP" icon="seti:php">
    <ChunkedSnippet source="..."  chunk="..."/>
  </TabItem>
</Tabs>

These conventions ensure a consistent presentation across all SDK examples, even as we add new languages.

Guide pages

Open Payments developer guides demonstrate complete workflows that combine multiple REST API operations. Each step typically shows one request/response sequence.

Writers should follow the broader framework in the Open Payments style guide for page elements like the page summary, scenario, endpoints list, and the steps in the guide. That guide also defines the formatting details for API requests and API responses.

Keep both request and response examples visually lightweight and predictable. Each should fit comfortably within a single screen view so readers can understand an operation at a glance. Refer to the following tips for both example requests and responses.

API request considerations

Example API requests should illustrate the endpoint, HTTP method, and relevant data.

• Keep payloads brief and realistic
• Include the parameters that can influence the specific response being demonstrated
• When different endpoints share common data (like wallet addresses or grants), display those values consistently throughout the guide so readers can easily recognize them

API response considerations

Example API responses should represent what relevant data comes back from the API, and it doesn’t always have to include a full payload.

• Emphasize what changed or what was created as a result of the request (for example, a new ID that was generated or a status that changed)
• Trim unrelated fields to keep the focus on the result shown
• Follow the same component pattern as SDK pages: a <details> block labeled “Example response” containing a short explanatory line and a json wrap block that matches the OpenAPI spec