114 lines
3.7 KiB
Markdown
114 lines
3.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):
|
|
|
|
## Adding a new SDK/language to examples pane
|
|
|
|
To add a new SDK/language to the right side examples pane:
|
|
|
|
- add the new language to the list of `languageOptions` in `/src/components/app.js`
|
|
to add it to the language toggle
|
|
- add to the list of SDKs in `/content/introduction.md` with a link to the SDK documentation
|
|
- add highlighting for the new language in `/src/highlight.js` by importing the
|
|
language and registering the language:
|
|
|
|
```
|
|
import java from 'highlight.js/lib/languages/java';
|
|
|
|
...
|
|
|
|
hljs.registerLanguage('java', java);
|
|
```
|
|
|
|
- add a test for the new SDK in `/test/content.js`:
|
|
|
|
```
|
|
it('has java example', () => {
|
|
expect(select(chunk, 'code[lang=java]').length).toBeGreaterThan(0);
|
|
})
|
|
```
|
|
|
|
- add a syntax-highlighted example to each method in each API -- if the new SDK
|
|
does not have methods for a particular API, include a syntax-highlighted
|
|
comment in the comment structure of the langauge saying that the API cannot
|
|
be accessed with this SDK.
|
|
|
|
## 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.
|