Naming Conventions

SFTI API Structure

Every SFTI common API specification contains at least the following objects in the defined order. ... indicates possible locations to extend the API specification. Each specification follows the provided structure:

openapi: Major.minor.bugfix
info:
  version: Major.minor.bugfix
  title: string
  description: string or multiline string
  contact:
    email: info@common-api.ch
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://...
externalDocs:
  description: Find out more about SFTI API specifications.
  url: https://www.common-api.ch

tags:
  - name: string
    description: string.
  - ...

security:
  - OAuth2:
      - read
      - write
      - ...
  ...

paths:
  ...

components:
  # Reusable schemas (data models)
  schemas:
    ...

  # Reusable path, query, header and cookie parameters
  parameters:
    ...

  # Security scheme definitions
  securitySchemes:
    OAuth2:
      ...
    ...

  # Reusable responses, such as 400 Bad Request or 401 Unauthorized 
  responses:
    ...

  # Reusable response headers
  headers:
    ...

Files are named according to their purpose and ending in API.yaml. For example, the SFTI API concering acccounts is therefore named accountAPI.yaml.

OpenAPI

This ruleset ensures compliance to the openAPI specification rules according to the used version within the SFTI API. To cover all rules we use the predefined rules provided by redocly.

Rules flagged with error must be adhered to. Rules flagged with warn should be followed as closely as possible.

Special rules

• no-unresolved-refs: error
  Every $ref must exist
• no-unused-components: warn
  All components must be used
• security-defined: error
  Security rules must be defined, either globally or per-operation
• spec: error
  Conform to the declared OpenAPI specification version
• spec-components-invalid-map-name: error
  Use only alphanumeric and basic punctuation as key names in the components section
• spec-strict-refs: error
  Restricts the usage of the $ref keyword.

Info

• info-contact: error
  Contact section is defined under info
• info-license: error
  License section is defined under info
• info-license-url: error
  License section contains a url to the license

Operations

• operation-2xx-response: warn
  Every operation needs at least one 2xx response
• operation-4xx-response: warn
  Every operation needs at least one 4xx response
• operation-4xx-problem-details-rfc7807: error
  All 4xx responses use RFC7807 format
• operation-description: warn
  Description field is required for every operation
• operation-operationId: warn
  OperationId is required for every operation
• operation-operationId-unique: error
  OperationId must be unique
• operation-operationId-url-safe: error
  OperationIds can only contain characters that are safe to use in URLs
• operation-summary: error
  Summary is required for every operation

Parameters

• no-invalid-parameter-examples: error
  Parameter examples must match declared schema types
• operation-parameters-unique: error
  No repeated parameter names within an operation
• parameter-description: warn
  Parameters must all have descriptions
• path-declaration-must-exist: error
  Paths must define template variables where placeholders are needed
• path-not-include-query: error
  No query parameters in path declarations (declare them as parameters with in: query)
• path-parameters-defined: error
  Path template variables must be defined as parameters

Paths

• no-ambiguous-paths: warn
  No path can match more than one PathItem entry, including template variables
• no-http-verbs-in-paths: error
  Verbs like "get" cannot be used in paths
• no-identical-paths: error
  Paths cannot be identical, including template variables
• no-path-trailing-slash: error
  No trailing slashes on paths
• path-segment-plural: error
  All URL segments in a path must be plural (exceptions can be configured)
• paths-kebab-case: error
  Paths must be in kebab-case format

Requests, Responses, and Schemas

• no-enum-type-mismatch: error
  Enum options must match the data type declared in the schema
• no-example-value-and-externalValue: error
  Either the value or externalValue may be present, but not both
• no-invalid-media-type-examples: error
  Example request bodies must match the declared schema
• no-invalid-schema-examples: error
  Schema examples must match declared types
• request-mime-type: warn
  Configure allowed mime types for requests
• response-mime-type: warn
  Configure allowed mime types for responses
• scalar-property-missing-example: error
  All required scalar (non-object) properties must have examples defined

Servers

• no-empty-servers: error
  Servers array must be defined
• no-server-example.com: warn
  example.com is not acceptable as a server URL
• no-server-trailing-slash: error
  Server URLs cannot end with a slash (paths usually start with a slash)
• no-server-variables-empty-enum: error
  Require that enum values are set if variables are used in server definition
• no-undefined-server-variable: error
  All variables in server definition must be defined

Tags

• operation-singular-tag: error
  Each operation may only have one tag
• operation-tag-defined: error
  Tags can only be used if they are defined at the top level
• tag-description: warn
  Tags must have descriptions
• tags-alphabetical: off
  Tags in the top-level tags section must appear alphabetically

SFTI

The SFTI ruleset ensures further alignment of SFTI specifications and enforces SFTI specific patterns in API specifications. Rules are aligned with best practices of ISO23029:2020. All rules are defined in the .github/redocly folder and applied within the redocly config file.

Please pay special attention to the ** rules because these rules are not technically enforced and must therefore be adhered to by the contributors. Rules flagged with error must be adhered to. Rules flagged with warn should be followed as closely as possible.

ISO 23029:2020: Web-service-based application programming interface (WAPI) in financial services

6 Naming conventions

• http-header: *
  Fields should be written in Train-Case (e.g Accept-Encoding)
  Acronyms should be written in capital letters (e.g JSON) **
• query-parameter: *
  Parameters in a query are written in snake_case (e.g data?user_id=12)
• request-body-keys: **
  Keys in a request body are written in snake_case (e.g {"user_id": 123})
• data-types: error
  Datatypes (i.e. schemas) named in UpperCamelCase (e.g CountryCode)

7 Resource path

• resource-type: *
  Names for resource types in plural (e.g users not user)
• resource-id: **
  Every resource is uniquely identified (e.g users/123)

8 WAPI styles

• composition-of-uri: **
  URI must follow the composition: https://{host}/{service}/{version}/{resource_path}?{parameters}
• attributes-and-search-criteria: **
  Put resource attributes and search criteria behind the ‘?’ (e.g ssis?currency=USD)
• specifying-multiple-allowed-values-for-an-attribute: **
  Use a comma separated list of values after the attribute’s name (e.g country=Belgium,Germany)
• modeling-OR-&-AND-filters: **
  Use & to indicate AND (e.g limit=25&offset=50) Use | to indicate OR (e.g category=electronics|clothing) Use the dot notation for subfields (e.g fields=address.city)
• http-response-codes: *
  HTTP status code 2xx when success HTTP status code 4xx or 5xx when failure, body with error element For more details on
• 4xx-response: *
  Media type application/problem+json as specified in RFC7807
  status: HTTP status code RFC7231 type: URI reference that identifies the type of problem
  title: Summary of problem type
  detail: Statement specific to this occurrence of the problem
  instance: URI reference that identifies the specific occurrence of the problem
• pagination-request: **
  limit to set the maximum number of objects to be returned, offset to specify the starting object of the page (e.g orders?limit=25&offset=50)
• pagination-answers: **
  Page header in the response body
  total count: Total number of objects available
  offset: Starting object of the page
  count: Number of object as specified in the limit
• news-subscription: **
  User agent and push service communicate via predefined JSON objects
  type: Operation of the push service
  topic: Topic of the push subscription

SFTI

Structure, Order and Required Objects

• root-object-order: error
  All objects are defined according to SFTI API structure
  All object are ordered according to SFTI API structure
• openapi-version: error
  Use openAPI version defined in redocly config file
• info-content: error
  Version must follow Semantic Versioning 2.0.0 schema (M.m.b)
  License must be Apache 2.0 and referenced by url http://www.apache.org/licenses/LICENSE-2.0.html
• externaldocs: error
  externalDocs description and url must be defined
  For SFTI Specs: externalDocs description must be: Find out more about SFTI API specifications. URL must be https://www.common-api.ch **
• component-order: error
  Components are ordered according to SFTI API structure: schemas, parameters, securitySchemes, responses, headers
• parameter-name-order: error
  Parameters are ordered by their type: in: path -> query -> header -> cookie
• parameter-object-order: error
  Parameters contain values in the following order: in -> name -> required (optional) -> schema -> description -> other values (optional)
• use-ref-when-used-multiple-times: warn **
  Objects used multiple times within the same SFTI specification should defined as references

Description

• info-description: error
  Info object must have a description field
  Description must end with a full stop
• tag-description: error
  Every tag object must have a description field
  Description must end with a full stop
• parameter-description: error
  Every parameter object must have a description field
  Description must end with a full stop
• schema-description: error
  Every schema and property object must have a description field
  Description must end with a full stop

Parameter

• path-parameter: error
  Path parameter name must be in camelCase format
  Path parameter name must end with 'Id'
  Path parameter reference must be named after path_ + parameter name
  Path parameter must be present in endpoint path **
• header-parameter: error
  Header parameter name must be in Train-Case format
  According to RFC 6648 custom header parameter name should not start with a specific pattern, like the widely used 'X-' prefix **
  Header parameter reference must be in snake_case format
  Header parameter reference must end with '_in_header'
  Optional header parameter reference must start with 'optional_'
• query-parameter: error
  Query parameter name must be in snake_case format
  Query parameter reference must be in snake_case format

---

* already enforced by redocly predefined or SFTI rules
** not technically enforced