Domaine de valeurs

API design principles

An important principle for API design and usage is Postel’s Law, aka The Robustness Principle (see also RFC 1122): Be liberal in what you accept, be conservative in what you send

Compatibility

MUST not break backward compatibility

application/x.<custom-media-type>+json;version=<version>

Accept: application/x.zalando.cart+json;version=2

Content-Type: application/x.zalando.cart+json;version=2

Vary: Content-Type

Deprecation: Tue, 31 Dec 2024 23:59:59 GMT
Sunset: Wed, 31 Dec 2025 23:59:59 GMT

Compatibility

• MUST prepare clients accept compatible API extensions
• SHOULD used open-ended list of values (x-extensible-enum) for enumerations
• SHOULD prefer compatible extensions

JSON guidelines

• SHOULD represent enumerations as strings
• SHOULD declare enum values using one the following five conventions for capitalizing identifiers : Upper Snake case, Snake case, Pascal case, Camel case or Uppercase format about enum value naming conventions.

Snake case

The snake case is a typographical convention in computer science consisting of writing sets of words, usually in lowercase, separated by underscores. Here are several examples of writing variable names according to the original spelling:

• « variable name » becomes variable_name
• « TopCamelCaseVariableName » becomes name_of_variable_upper_camel_case
• « Variable » becomes variable
• « variable » becomes variable (no change)

Pascal case

The first letter in the identifier and the first letter of each subsequent concatenated word are capitalized. You can use Pascal case for identifiers of three or more characters. For example: PascalCase

Camel case

The camel case is a notation consisting of writing a set of words by linking them without spaces or punctuation, where the first letter of an identifier is lowercase and the first letter of each subsequent concatenated word is capitalized. For example: backColor. This term refers to the hollows and bumps of a camel’s back represented by the alternation of lowercase and capitals 

Uppercase

All letters in the identifier are capitalized. Use this convention only for identifiers that consist of two or fewer letters. For example: System.IO System.Web.UI

Reference

1. https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-1.1/x2dbyw72(v=vs.71)?redirectedfrom=MSDN
2. http://gdt.oqlf.gouv.qc.ca/ficheOqlf.aspx?Id_Fiche=26543803
3. http://gdt.oqlf.gouv.qc.ca/ficheOqlf.aspx?Id_Fiche=26543805
4. https://fr.wikipedia.org/wiki/Snake_case

SHOULD prefer compatible extensions

• Enum ranges can be reduced when used as input parameters, only if the server is able to explain the reason (return an error) why the value is no longer allowed, eg dissolution of a country;
• Enum ranges can be extended when used for input parameters;
• Enum range can be reduced when used as output parameters;
• Enum ranges cannot be extended when used for output parameters — clients may not be prepared to handle it. Enums must be able to accept values of type ‘UNKNOWN’;
• Use x-extensible-enum, if range is used for output parameters and likely to be extended with growing functionality. It defines an open list of explicit values and clients must be agnostic to new values.

MUST prepare clients accept compatible API extensions

Service clients must be prepared for compatible API extensions of service providers:

• Be prepared that x-extensible-enum return parameter may deliver new values; either be agnostic or provide default behavior for unknown values.

SHOULD used open-ended list of values (x-extensible-enum) for enumerations

• Enumerations are per definition closed sets of values, that are assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid these issues, we strongly recommend to use an open-ended list of values instead of an enumeration unless:
  • the API has full control of the enumeration values, i.e. the list of values does not depend on any external tool or interface, and
  • the list of value is complete with respect to any thinkable and unthinkable future feature.
  • Examples : List of days, months, quarters, boolean (TRUE/FALSE)

To specify an open-ended list of values use the marker x-extensible-enum as follows:

delivery_methods:
type: string
x-extensible-enum:
– PARCEL
– LETTER
– EMAIL
default: EMAIL
description: Intended about delivery methods

Note: x-extensible-enum is not JSON Schema conform but will be ignored by most tools.

SHOULD represent enumerations as strings

Strings are a reasonable target for values that are by design enumerations.

MUST not use null for boolean properties

Schema based JSON properties that are by design booleans must not be presented as nulls. A boolean is essentially a closed enumeration of two values, true and false. If the content has a meaningful null value, strongly prefer to replace the boolean with enumeration of named values or statuses – for example accepted_terms_and_conditions with true or false can be replaced with terms_and_conditions with values yes, no and unknown.

Enums

You can use the enum keyword to specify possible values of a request parameter or a model property. For example, the sort parameter in GET /items?sort=[asc|desc] can be described as:

paths:
    /items:
      get:
        parameters:
          - in: query
            name: sort
            description: Sort order
            schema:
              type: string
              enum: [asc, desc]

In YAML, you can also specify one enum value per line:

enum:
  - asc
  - desc

All values in an enum must adhere to the specified type. If you need to specify descriptions for enum items, you can do this in the description of the parameter or property:

parameters:
  - in: query
    name: sort
    schema:
      type: string
      enum: [asc, desc]
    description: >
      Sort order:
       * `asc` - Ascending, from A to Z
       * `desc` - Descending, from Z to A

Nullable enums

A nullable enum can be defined as follows:

type: string
nullable: true  # <---
enum:
  - asc
  - desc
  - null        # <--- without quotes, i.e. null not "null"

Note that null must be explicitly included in the list of enum values. Using nullable: true alone is not enough here.

Reusable enums

In OpenAPI 3.0, both operation parameters and data models use a schema, making it easy to reuse the data types. You can define reusable enums in the global components section and reference them via $ref elsewhere.

paths:
  /products:
    get:
      parameters:
      - in: query
        name: color
        required: true
        schema:
          $ref: '#/components/schemas/Color'
      responses:
        '200':
          description: OK
components:
  schemas:
    Color:
      type: string
      enum:
        - black
        - white
        - red
        - green
        - blue

Specification Extensions

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are implemented as patterned fields that are always prefixed by « x-« .

The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).