Skip to content

Style Guide Common APIs

Jump to bottom
dkoeni edited this page Jul 15, 2024 · 13 revisions

How To Write our APIs?

General Remarks and Style Guide

Best practice yaml syntax
APIs are defined according to the OpenAPI Specification (OAS). OAS specifies OpenAPI documents in either YAML or JSON style. SFTI APIs follow the YAML style. Besides the general Schema (c.f. Swagger documentation) we make some additional conventions for reasons of consistency.

The style guides are checked automatically by yamllint v1.31.0 on every created Pull Request. The pipline automatically checks that the above defined guidelines are applied to the ca-APIs comprehensively. Please keep warnings at a minimum and ignore them only if its reasonable. Be aware that this linter is still a static checking of the provided code, so it might be possible to fool the linter and bypass the rules. Also this is not desired.

Style Guide Rules

  • Braces
    Only empty braces () and {} are allowed. Otherwise use indents and dashes to avoid braces. Empty braces must not contain whitespace.
  • Brackets
    Only empty brackets [] are allowed. Otherwise use indents and dashes to avoid brackets. Empty brackets must not contain whitespace.
  • Colons
    No whitespace must be present before a colon, and exactly one after a colon.
  • Commas
    No whitespace must be present before a comma, and exactly one after a comma.
  • Comments
    Comments must be start with a hashtag followed by a whitespace (# ) sequence, shebangs (#!) are ignored. Inline comments require at least 2 whitespace between code and comment.
  • Comments-indentation
    Comments should be aligned with and intended as their corresponding content.
  • Empty-lines
    In a yaml file only 2 consecutive empty-lines are allowed. No empty-line should be added at the begging or the end of a file.
  • Empty-values
    Empty values should be omitted and explicitly stated as empty.
  • Hyphens
    After a dash e.g used in dict there must be exactly one whitespace.
  • Indentation
    Indentions are considers to be 2 spaces long and have to be consistent in the number of indents. Multi-line strings must also be indented as the first line.
  • Key-duplicates
    No key duplicates are allowed.
  • Line-length
    Use this rule to set a limit to lines length.
  • New-line-at-end-of-file
    At the end of the file there must be exactly one new-line following the POSIX standard.
  • New-lines
    When committing changes to GitHub one must ensure that line endings are converted into unix newlines.
  • Quoted-strings
    Strings must only be quoted when necessary except regex pattern indicated by the pattern: keyword. When needed, strings must be quoted with single quotes. Quoted quotes are allowed.
  • Trailing-spaces
    Whitespaces at line endings must be removed. Multiline documentation strings (ideally using the yaml multiline formatter) are excepted from this rule. Those comments may end with double spaces in the end to indicate a markdown new-line.
  • Truthy
    As truth values only true or false should be used.

For any yamllint error you might might not understand (yamllint error messages are sometimes kind of cryptic) please refer to the official yamllint documentation and map the defined rules to the SFTI yamllint configuration file, since this style guide closely follows those configured rules.

Field order
See Nice to Have section.

How to Document? Our Documentation Guide

TL;DR here are your style rules:

  • inline documentation
  • summary describes more general as the description field and no duplicates
  • summary without a point at the ending, description with
  • use as many fields as useful

Inline documentation
In general, we use the approach to document with inline descriptive strings. For this purpose, the description field can be used. As far as useful, every field should contain a description with a short, non-redundant statement of purpose.

Summary & description
Use summary tags to summarize an endpoint's task. The summary should be written bullet-point like and with no point at the end of the sentence. The overall description should provide more details about the task than the summary. The description contains a few sentences ending with a point. Other description tags like parameter descriptions may end with or without a point.

If you want to provide a summary or description, that exceeds one single line in common editors, please consider using YAML block style indicators to split the description into multiple lines while achieving your intended highlighting.

Fields
In addition, parameter fields should also provide an example field, and a default OR required field if applicable. Be aware that the required keyword overwrites default fields since the parameter must be set by the user. All those fields should be used extensively.

Optional Feature:
Automated documentation creating tools like Swagger UI support basic markdown for description fields. Unfortunately, online swagger UI (see here) does not support this feature. Nevertheless, it may be helpful to use markdown to highlight different or important details. Markdown should be used as follows.

  • for now, use markdown as it seems fit
  • tbd

Nice to Have

From now on, we highly suggest implementing an order of fields. That means all fields are ordered by a specific rule and will always occur in this way. Omitted fields will be ignored and the order will preserve without those.

  1. The summary field is always before the description field, since the summary gives an overall description.
  2. For parameters, we will use the following order:
parameters:
  - in: path
    name: exampleParameter
    required: true
    schema:
      type: data type
      minimum: min
      maximum: max
      pattern: '[A-Za-z]{0-9}'
      default: default value
    example: this parameter looks like this 
    description: path parameter

Example

In this section, we provide a schematic example that contains a full and well-defined API according to this style and documentation guide.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Example API
  description:
    This API deserves as an example where you find all rules from the guide applied.
  contact:
    email: max@muster.ch
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: https://example.api.ch
externalDocs:
  description: Find out more about this example API above
tags:
  - name: Example Tag
    description: provide details about this tag
paths:
/example-case/{exampleParameter}:
  get:
    summary: Brief summary of this endpoint
    description: More detailed description what happens here, e.g. purpose, how to use, required parameter.
    tags:
      - Example Tag
    parameters:
      - in: path
        name: exampleParameter
        required: true
        schema:
          type: string
        example: this parameter looks like this 
        description: path parameter
      - in: query
        name: language
        schema:
          type: string
          enum:
            - de
            - fr
            - it
            - en
          default: en
        example: fr
        description: Language of the example API.
      - $ref: '#/components/parameters/example'
    responses:
        '200':
            description: OK
            headers:
                Example-Header:
                schema:
                    type: string
                description: Example header set in response.
            content:
                application/json:
                $ref: '#/ref/to/not-existing/json/reference-object'

components:
  parameters:
    example: 
      in: query
      name: globalExample
      schema:
        type: integer
        minimum: 0
        maximum: 20
        default: 3
      example: 10
      description: >
        Global example parameter (SCOPE: Ex). Note, use quotes here due to the colon.

Wiki

Collaboration Essentials

API Design Basics

Common Implementation Guidelines

Release Management

Appendix

Repo Wikis

Clone this wiki locally