Design Guidelines

  • Do not reinvent the wheel - Use existing concepts whenever possible (e.g. type system of OpenAPI, Problem details,…).
  • Strive for a Level 3 of REST maturity.
  • Use semantic versioning.

Derived Guidelines

  • Whenever a resource returned in a response can contain embedded resources, the request must allow specifying whether and which embedded resources should be returned in full or as references.
  • Follow Zalando RESTful API and Event Scheme guidelines
  • Use of the JSON Problem element
  • Standard Patch operations (not JSON PATCH)
  • A resource is either represented in full or as a reference. The reference element has the name of the resource post-fixed with “Ref”. References normally only contains the URL to the referenced resource and a title element allowing to summarize the resource in one short string
  • Although examples or recommendations are provided as to which information should best be represented in the title string, each implementor as the freedom to modify it to best suit his needs.
  • Enumerations for very stable entities with limited set only, otherwise code lists. Stations codes are code lists.
  • Where possible, existing UIC code lists should be favored.
  • Creation/ modification calls return the created/modified resource (not just an ok code)

Error Handling

In order to communicate errors to a consumer we support RFC7807.

This RFC defines a “problem detail” as a way to carry machine- readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

A problem details object can have the following members:

  • type: A URI reference RFC3986 that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be “about:blank”.
  • title: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see RFC7231, Section 3.4).
  • status: The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
  • detail: A human-readable explanation specific to this occurrence of the problem.
  • instance: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Consumers MUST use the type string as the primary identifier for the problem type; the title string is advisory and included only for users who are not aware of the semantics of the URI and do not have the ability to discover them (e.g., offline log analysis). Consumers SHOULD NOT automatically dereference the type URI.

Functional Errors and Error Codes

In order that OSDM implementations behave consistently in error situations, a list of error codes and warnings have been defined that must be supported in case of functional errors by all implementations.

Authentication

The following three design principles are binding for each implementor:

  1. Don’t reinvent crypto, thus we are using OAuth2.

  2. The JWTs in use for the authentication should be short-lived (think of timeout duration single-digit multiples)

  3. The JWTs sent by the consumer, regardless of where they are generated, must be digitally signed using a private key for which the provider is able to find the matching public key

These principles can be implemented as follows:

  • A registration service allows a consumer to register the necessary data (like: organization, technical admin, commercial admin, support line, other non-functional requirements like throttling limits) for approvement by the team providing access. any registered consumer will be approved or rejected if approved a unique, technical “ClientId” results and will be passed to the consumer

  • A login service allows to request a valid token (for e.g. OAauth2) by the registered ClientId and related secret per configuration the validity duration of the token may be set (for e.g. 10min.), after that the token must be renewed by the consumer optionally the token might be revoked (for e.g. if your devOps realizes the consumer does not behave as expected)

In multi-environments (like DEV, TEST, INT, PROD) consumers might register for each environment separately.

The detailled flow for machine-to-machine authentication can be found in Authentication.

User Lookup

From a devOps perspective it might by hard to control who uses your API (for e.g. ClientId and secret might by passed around or hacked).

The following issues should be defined outside of OSDM:

  • Additional legal contracts with consumer
  • IP white listing
  • Mapping of related user properties to the technical ClientId