# Documentation Style Guide **Table of contents:** - [Overview](#overview) - [Parameter names](#parameter-names) - [Path parameter names](#path-parameter-names) - [Query parameter names](#query-parameter-names) - [General parameter rules](#general-parameter-rules) - [Enumeration values](#enumeration-values) - [Query parameter enum values](#query-parameter-enum-values) - [Schema enum values](#schema-enum-values) - [File names](#file-names) - [Path file names](#path-file-names) - [Parameter file names](#parameter-file-names) - [Schema file names](#schema-file-names) - [Request schema file names](#request-schema-file-names) - [Response schema file names](#response-schema-file-names) - [Display names](#display-names) - [Example code](#example-code) - [Request examples](#request-examples) - [Parameter examples](#parameter-examples) - [Response examples](#response-examples) - [Deprecation labels](#deprecation-labels) - [Admonitions such as Note, Warning, and Important](#admonitions-such-as-note-warning-and-important) - [Admonitions in articles, tag descriptions, and operation descriptions](#admonititions-in-articles-tag-descriptions-and-operation-descriptions) - [Admonitions in parameter and property descriptions](#admonitions-in-parameter-and-property-descriptions) ## Overview This document describes conventions for creating and modifying API specifications and descriptions. > **Note:** `` denotes the product API you're editing. ## 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 `camelCase`. - **Prefixing:** Prefix with the resource name for commonly parameterized attributes (e.g., IDs, types, statuses). Note, existing services may dictate the parameter name. **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 `camelCase`. - **Prefixing:** Prefix with the resource name for commonly parameterized attributes (e.g., IDs, types, statuses). Note, existing services may dictate the parameter name. **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 `camelCase`. **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 `camelCase` parameters in `{}` braces. The [`redocly split`](https://redocly.com/docs/cli/commands/split) command uses this convention. - **File location:** Use the `api//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 calling [`redocly split`](https://redocly.com/docs/cli/commands/split) via the `npm run split` command (or the respective `split:*` command for Brandfolder or Resource Management). ### Parameter file names - **Casing:** Use `camelCase`. - **File location:** Use the `api//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 `PascalCase`. - **File location:** Use the `api//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:** `[Request].yaml` **Examples:** ``` CommentCreateRequest.yaml SummaryFieldUpdateRequest.yaml Favorite.yaml # The schema is used in a request and a response ``` **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 `Request` suffix; otherwise use it. #### Response schema file names **Format:** `[Response].yaml` **Examples:** ``` UserProfileImageResponse.yaml Favorite.yaml # The schema is used in a request and a response ``` **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.) If the schema represents a list item, use the format `[Response]ListItem.yaml`, where `Response` is optional. For example, `AddedColumnResponseListItem.yaml` in the [**Add columns**](/assets/sheets_sheetid_columns.c39a3fbb38d27c2968194dac645466079b6d525eef2434166248cf852740df39.3f194408.yaml) operation. ## Display names Our operation and schema names show in site navigation. **Casing:** Use `Sentence case`. **Examples:** ``` List users Widget type ``` **Element display name properties:** | Element | Property | Example | | --- | --- | --- | | Path | `paths...summary` | `summary: List users` | | Schema | `components.schemas..title` | `title: 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: ```yaml 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](https://developers.smartsheet.com/api/smartsheet/openapi/events/list-events) examples, we only wanted to show using the `since` and `to` query parameters. So we created overrides for the request examples. ```bash 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 ' ``` ### 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//changelog.md` file. 2. Set `deprecated: true`, if specification element is one of these: - operation - parameter - schema property Only the above elements support using the `deprecated:` OpenAPI property. 3. End the element's `description:` with a deprecation note. Here are some example notes: ``` **DEPRECATED - As early as the sunset date specified in this [Changelog entry](/api/smartsheet/changelog#YYYY-MM-DD), .** ``` 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 functionality is 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.** ``` For deprecation process details, see the [2.0 API Deprecation Process Guidelines for Teams](https://smar-wiki.atlassian.net/wiki/spaces/DEV/pages/73101181038/2.0+API+Deprecation+Process+Guideline+for+Teams) wiki page. > **Important:** When you start creating your Merge Request, follow the instructions in the Merge Request form. ## Admonitions such as Note, Warning, and Important You can use admonitions to warn users, call out important information, or share ancillary, side information. Here's some guidance on when to use each. - **Note:** is for information that may be helpful or interesting, but that is not essential to the main purpose of the content. For example, **Note:** Although the example code is written in JavaScript, you can use any language that supports ABC. - **Warning:** is for alerting users to something that they should avoid or must take extra care with using. For example, **Warning:** Your API token provides programatic access to your Smartsheet content. Never share your API token publicly. - **Important:** is for emhpasizing significant information. For example, **Important:** While your token value is visible in the user interface, copy it to a safe place to enter in API requests later. ### Admonititions in articles, tag descriptions, and operation descriptions In articles, tag descriptions, and operation descriptions, use block quote syntax to make your admonition stand out. For example, > **Note:** Although the example code is written in JavaScript, you can use any language that supports ABC. ### Admonitions in parameter and property descriptions Redocly renders parameter and property documentation in tight, tabular format where block quotes look awkward. As such, don't block quote admonitions in parameter and property descriptions. For example, **Note:** This property only shows for System Admins.