Rule: Centralize the definition of key concepts and terms
Rationale:
Do not presume prior knowledge of terms or concepts. Ensure that your explanations are easily understandable to readers who may be unfamiliar with the subject matter. Establish a dedicated section for defining and explaining frequently used terms and concepts and incorporate links within pertinent field descriptions. When employing acronyms, provide clear definitions upfront, such as in a Common Terms section or an API glossary.
paths:/data-integration:post:summary: Initiate data integrationdescription: | Initiates a `[data integration process] (/data-integration-guide.html)`, extracting data from various sources and unifying it into a centralized data store.
paths:/data-integration:post:summary: Initiate data integrationdescription: | Initiates a data integration process.
Rule: Describe complex boolean behaviors
Rationale:
When dealing with boolean fields, explain both TRUE and FALSE behaviors when they are not simply opposites.
parameters:- name: publishin: querydescription: | TRUE publishes the blog post instantly. FALSE saves it as a draft.schema:type: boolean
parameters:- name: publishin: querydescription: | TRUE publishes the blog post instantly.schema:type: boolean
Rule: Define explicit date formats
Rationale:
Neglecting to specify date formats can lead to misinterpretation, inconsistencies across the API, and integration complications.
For instance, your API might use date formats like "date" (YYYY-MM-DD) or "date-time" (RFC 3339 restricted format). To prevent confusion, it's crucial to clearly inform API users about the expected format. Include an illustrative example using the example property. When feasible, centralize the description of date formats, particularly if your API maintains a consistent date format throughout.
parameters: - name: start_datein: querydescription: | Start date and time for filtering data in [RFC 3339 format] (https://datatracker.ietf.org/doc/html/rfc3339).schema:type: stringexample: "2022-07-21T17:32:28Z"
parameters: - name: start_datein: querydescription: | Start date and time for filtering data.schema:type: string
Rule: Utilize the "default" property for parameter defaults
Rationale:
Employ the "default" property to indicate default values as metadata, diminishing the likelihood of descriptions becoming obsolete.
parameters:- name: deliveryOptionin: querydescription: | An optional parameter to choose a delivery option.default: "STANDARD"schema:type: string
parameters:- name: deliveryOptionin: querydescription: | An optional parameter to choose a delivery option that defaults to STANDARD.schema:type: string
Rule: Convey verb-object-response in endpoint summaries
Rationale:
Endpoint summaries should start with an action verb (based on the method), reference the targetted object, and convey the expected response.
paths:/products:get:summary: Retrieve a list of available products.
paths:/products:get:summary: List of available products.
Rule: Show examples using the examples property
Rationale:
When providing examples in your API documentation, use the example property rather than embedding them within the field description.
Storing examples as metadata allows tools and platforms to efficiently extract and display examples, ensuring they are correctly formatted and stand out for developers to easily reference, as well as analyze examples for specific purposes.
parameters: - name: transactionAmountin: querydescription: | The amount of the financial transaction.schema:type: numberformat: doublemultipleOf: 0.01example: 100.50
parameters: - name: transactionAmountin: querydescription: | The amount of the financial transaction. Example: 100.50schema:type: number
Rule: Clarify interactions between fields
Rationale:
For a given operation, when two or more fields work in conjunction to produce a specific result, describe their relationship and the expected outcome. Are there any dependencies, constraints, or expectations when multiple fields are used simultaneously?
paths:/devices:post:summary: Configure IoT device sensorsdescription: | This operation has the following parameters: - `sensorType`: Specifies the type of sensor (e.g., temperature, humidity). - `samplingInterval`: Determines how often the sensor takes readings. - `threshold`: Sets a value that triggers an alert when sensor data exceeds it. When a `temperature` sensor is selected, the `samplingInterval` should not be set too frequently to conserve power. The `threshold` value might need to be configured within a certain range for meaningful alerts.
Rule: Distinguish metadata from descriptive content
Rationale:
Elaborating on metadata-related particulars can risk becoming outdated as the API evolves. For example, for strings, specify character limits and format constraints. For numbers, specify range, precision, and units for numeric values. For arrays, specify permissible values and size restrictions. For dates/times, specify date and time formatting and time zone specifications. For enums, specify eumeration values. Concentrate your documentation on elements that cannot be encompassed within metadata. As exemplified in the 'good' instance provided below, the unit 'meters' cannot be fully conveyed via metadata and should, therefore, be incorporated within the field's description.
parameters: - name: distancein: queryschema:type: numberdescription: | Maximum distance in meters.minimum: 0maximum: 100multipleOf: 5
parameters: - name: distancein: queryschema:type: numberdescription: | Maximum distance in meters. Specify a value within the range of 0 to 100, and it must be a multiple of 5.