Last updated

Documentation Style Guide

Table of contents:

Overview

This document describes conventions for creating and modifying API specifications and descriptions.

Note: <product> denotes the product API you're editing. Currently, we only have smartsheet but the brandfolder and Resource management APIs are also being migrated to this project.

Parameter names

To ensure consistency, clarity, and predictability across the API, follow these naming conventions for all path and query parameters.

Path parameter names

  • Casing: Use lowerCamelCase.
  • Prefixing: Always prefix with the resource name for commonly parameterized attributes (e.g., IDs, types, statuses).

Examples:

/users/{userId}
/shares/{shareId}
/users/{userId}/deactivate
sheets/{sheetId}/proofs/{proofId}

Guidelines:

  • Avoid abbreviations unless they are widely understood (e.g., "Id" is acceptable for "identifier").
  • Use meaningful and descriptive names.
  • Do not include the {} braces in the parameter definition — they are part of the path syntax, not the parameter name.

Query parameter names

  • Casing: Use lowerCamelCase.
  • Prefixing: Always prefix with the resource name for commonly parameterized attributes (e.g., IDs, types, statuses).

Examples:

/users?userId=123&status=active
/projects?projectType=internal&createdAfter=2024-01-01
/orders?orderId=456&orderStatus=pending
/tasks?assigneeId=789&dueDateBefore=2024-12-31

Guidelines:

  • Use clear, descriptive names.
  • Avoid generic names like id or type without a resource prefix.
  • Maintain consistent order and naming across endpoints when possible.

General parameter rules

  • Be consistent throughout the API.
  • Avoid unnecessary abbreviations or short forms.
  • Make parameter names self-explanatory and predictable.
  • Describe parameters clearly in the OpenAPI spec to help consumers understand their meaning.

Example combined usage:

GET /projects/{projectId}/tasks/{taskId}?assigneeId=789&dueDateBefore=2024-12-31

Enumeration values

Query parameter enum values

Casing: Use lowerCamelCase.

Examples:

attachments
summaryFields
cellLinks

Schema enum values

Casing: Use UPPER_SNAKE_CASE.

Examples:

ABSTRACT_DATE_TIME
CHECKBOX
CONTACT_LIST

File names

Path file names

  • Casing: Use lower_snake_case with lowerCamelCase parameters in {} braces. The redocly split command uses this convention.
  • File location: Use the api/<product>/paths/ folder (e.g., api/smartsheet/paths/).

Examples:

users_{userId}.yaml
sheets_{sheetId}_rows_{rowId}.yaml
users_{userId}_deactivate.yaml
sheets_{sheetId}_summary.yaml

Guidelines:

Name path files based on the endpoint path and path parameters.

Tip: First, specify your path in your product's openapi.yaml file. Then, extract the path to a file, by executing the redocly split <path> --outDir=<anotherDir> command.

Parameter file names

  • Casing: Use lowerCamelCase.
  • File location: Use the api/<product>/components/parameters/ folder (e.g., api/smartsheet/components/parameters/).

Examples:

altText.yaml
lastKey.yaml

Guidelines:

  • If the parameter is used only once, specify it in the path file.
  • Base the file name on the parameter name.

Schema file names

  • Casing: Use UpperCamelCase.
  • File location: Use the api/<product>/components/schemas/ folder (e.g., api/smartsheet/components/schemas/).

Guidelines:

If a schema is uncomplicated and used only once, specify it in the path file; otherwise specify it in a separate schema file.

Request schema file names

Format: <Resource>[<Creation|Update|Deletion|Get>Request].yaml

Examples:

Favorite.yaml  # The schema is used in a request and a response
CommentCreationRequest.yaml
SummaryFieldUpdateRequest.yaml

Guidelines:

  • If the schema is used only once, specify it in the path file.
  • Base the file name on the resource being acted on.
  • If the schema is used in a request and a response, don't use the <Action>Request suffix; otherwise use it.

Response schema file names

Format: <Resource>[Response].yaml

Examples:

Favorite.yaml  # The schema is used in a request and a response
UserProfileImageResponse.yaml

Guidelines:

  • If the schema is used only once, specify it in the path file.
  • Base the file name on the related resource(s).
  • If the schema is used in a request and a response, don't use the Response suffix; otherwise use it. (Note: Most existing response schemas don't use the suffix, but the suffix helps to describe the schema purpose.)

Display names

Our operation and schema names show in site navigation.

Casing: Use Sentence case.

Examples:

List users
Widget type

Element display name properties:

ElementPropertyExample
Pathpaths.<path>.<operation>.summarysummary: List users
Schemacomponents.schemas.<schema>.titletitle: Widget type

Example code

Redocly Realm supports request and response code examples.

Request examples

Unless you override a request example, Redocly Realm generates them based on your specified operation. It generates examples in several languages automatically.

Important: You can override request examples only--response examples are generated based on the response schema and example property values.

Here's an example Node.js request override:

get:
  x-codeSamples
    - lang: 'Node.js'
      label: 'Node.js'
      source: |
        // Set options
        var options = {
          workspaceId: 7116448184199044
        };

        // Get workspace
        smartsheet.workspaces.getWorkspace(options)
          .then(function(workspace) {
            console.log(workspace);
          })
          .catch(function(error) {
            console.log(error);
          });

If you only want an example(s) to show using a subset of the query parameters, you must override the example request.

For example, in List events operation examples, we only wanted to show using the since and to query parameters. So we created overrides for the request examples.

  x-codeSamples:
    - lang: 'cURL'
      label: 'cURL'
      source: |
        curl -i -X GET \  
        'https://api.smartsheet.com/2.0/events?since=2025-03-24T15%3A15%3A22Z&to=2025-03-24T16%3A15%3A22Z' \
        --header 'Accept-Encoding: deflate' \
        --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Parameter examples

Unless you override the request examples, Redocly Realm generates request code that includes each parameter, with its example value (if present) or type default value.

Response examples

Redocly Realm shows each object property in the response. If you specify an example for a property, that example value shows for the property; otherwise, the type default value shows.

Tip: Make responses realistic by setting the example properties for the object properties compatible with the request.

Deprecation labels

Here's how to label deprecations:

  1. Describe the deprecation in a changelog entry. See the commented instructions in the api/<product>/changelog.md file.

  2. Start the element's description: with the following content:

    **DEPRECATED - As early as the sunset date specified in this [Changelog entry](/api/smartsheet/changelog#YYYY-MM-DD), <describe what will happen to this feature>.** <Optionally, add more details in NON-bold text here.>

    Example 1:

    **DEPRECATED - As early as the sunset date specified in this [Changelog entry](/api/smartsheet/changelog#YYYY-MM-DD), this endpoint will no longer support [offset-based pagination](TODO) and will instead support [token-based pagination](TODO).** The following parameters are affected: <On separate lines below, list the affected parameters and describe how they're affected>

    Example 2:

    **DEPRECATED - As early as the sunset date specified in this [Changelog entry](/api/smartsheet/changelog#YYYY-MM-DD), this response property will have a `-1` value.**

  3. Set deprecated: true, if specification element is one of these:

    • operation
    • parameter
    • schema property

    Only the above elements support using the deprecated: OpenAPI property.

For deprecation process details, see the 2.0 API Deprecation Process Guidelines for Teams wiki page.

Important: When you start creating your Merge Request, follow the instructions in the Merge Request form.