Skip to content

Latest commit

 

History

History
82 lines (57 loc) · 2.72 KB

CONTRIBUTING.md

File metadata and controls

82 lines (57 loc) · 2.72 KB
Raw

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?)
  • 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:

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 or another more tasteful formatter.