83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
## Topics
|
|
|
|
Topics contain information that applies to web services in general (not specific to APIs).
|
|
|
|
## API endpoints
|
|
|
|
Each individual API should have its own markdown file in the /content directory. Use snake case for filenames.
|
|
|
|
Each API file should have:
|
|
|
|
- H2 naming the API (i.e. "Wobbles")
|
|
- description of the API
|
|
- H3 naming the object or resource that is retrieved/created/deleted by the API
|
|
- description of the method
|
|
- list of parameters
|
|
- example requests and responses
|
|
|
|
Make sure the API is also included in the nav by adding it to `content.js`.
|
|
|
|
### Description
|
|
|
|
A one- or two-sentence description explaining what the API does (not how to use it).
|
|
|
|
### Object
|
|
|
|
Each API should have a description of the primary resources returned and manipulated
|
|
using the API.
|
|
|
|
- H3 naming the object (i.e. "The wobble object")
|
|
- One sentence explaining what the object is.
|
|
- Two-column table to describe the object:
|
|
- property name / type / required
|
|
- property description
|
|
- If the object is severely nested, use a nested list instead of a table
|
|
|
|
### Methods
|
|
|
|
List all methods for interacting with the API.
|
|
|
|
Each method:
|
|
|
|
- H3 naming the method (i.e. "Retrieve a font")
|
|
- Endpoint (h4?)
|
|
- do not include base URL in endpoint
|
|
- endpoints should use [three backtick markdown format with syntax highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) with `url` as the language
|
|
- A description of what the method does. (NOT how to use it.)
|
|
- (how do we define scopes?)
|
|
- If necessary, a description of accepted values/filetypes and limits/restrictions
|
|
- Two-column table to describe parameters
|
|
- parameter name
|
|
- parameter description and accepted values
|
|
|
|
### Examples
|
|
|
|
Each method should have H4 headers for examples:
|
|
|
|
- Example request
|
|
- Example request body (if applicable)
|
|
- Example response
|
|
|
|
There should be four examples under each header, one for each library. Use
|
|
[three backtick markdown format with syntax highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting):
|
|
|
|
## Style conventions
|
|
|
|
- Always JSON, never `JSON` or json.
|
|
- Do **not** include access tokens in example URLs.
|
|
- h2 and h3 will be included in side nav
|
|
- code blocks/h4/blockquotes will be pushed to the right
|
|
|
|
## Lingo
|
|
|
|
- the parts of a JSON object are called **properties**
|
|
- querystring parameters are called **parameters**
|
|
|
|
## Formatting JSON
|
|
|
|
We need to show JSON examples, but we want to make the documentation readable
|
|
on a wide range of monitors: so it needs to be somewhat narrow and compact.
|
|
Usually stringifying JSON with indentation of 2 spaces does the trick:
|
|
if that isn't enough, use [json-pretty-compact-cli](https://github.com/tmcw/json-pretty-compact-cli)
|
|
or another more tasteful formatter.
|