Documentation Guidelines for REST APIs

Use these guidelines for Splinter REST API (OpenAPI) documentation.

• Follow Splinter’s general documentation guidelines and capitalization guidelines.

• Include both a summary and a description for each method (GET, POST, etc.).

  • For the method summary, use a very short phrase. Don’t add final punctuation.

  • For the method description, use a full sentence that ends with a period. Feel free to use multiple sentences or a few paragraphs, if necessary.

  • For example:

    summary: Lists all doohickeys
    description: Fetches a list of doohickeys for the thingamajig.
  

  
  

• Use consistent wording for the HTTP verbs. For example:

  Start a GET summary with a verb that ends with s:

  • “Lists” if the method returns a list.
  • “Gets” if it returns a non-binary value.
  • “Checks” if it returns a binary value.
    
    

  Start a GET description with a different verb that ends with s:

  • “Fetches a list” if the method returns a list.
  • “Returns …” if it returns a non-binary value.
  • “Verifies” if it returns a binary value.
    
    

• For more guidelines:

  • See swagger.io’s best practices in API documentation. Scroll to the subheading “Best Practices in API Documentation” for specific tips and good examples.

  • For JavaScript, use Google’s guide for JavaScript comments.

  • Go beyond the basics: Provide an overview, a getting started guide, a full description of the request-response cycle, and links to SDKs and code libraries. See API Documentation Beyond the Basic Swagger UI.

  • See this example: Surfreport API documentation (idratherbewriting).