Skip to content
GitHub

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 within 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:

Documenting GraphQL examples

We’ve created a standardized format to maintain a consistent look and feel when documenting example GraphQL queries and mutations. Each GraphQL example should be organized 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.

Operation tab

  • Include the query/mutation in a code block
  • Specify graphql as the language for syntax highlighting
  • Do not include the query/mutation name in 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>

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="Arguments">
    ```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

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

REST API

Coming soon