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 havesmartsheet
but thebrandfolder
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
ortype
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
withlowerCamelCase
parameters in{}
braces. Theredocly 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 theredocly 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:
Element | Property | Example |
---|---|---|
Path | paths.<path>.<operation>.summary | summary: List users |
Schema | components.schemas.<schema>.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:
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:
Describe the deprecation in a changelog entry. See the commented instructions in the
api/<product>/changelog.md
file.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.**
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.