Skip to content
Snippets Groups Projects
user avatar
Jonas Groeger authored
usually we use the OAuth2 security schema. but public endpoints
do not have this security constraint. callbacks don't authenticate
against the called endpoint.

For reference, the warning was (one example):

> Every operation should have security defined on it or on the root level.
>
> 418 | get:
>     | ^^^
> 419 |   operationId: get-destination-key
> 420 |   summary: Ruft einen JWK des Zustelldienstes ab
>
> Warning was generated by the security-defined rule.
6951623d
History

FIT-Connect API specification

Rules

General

  • We use OpenAPI 3.1.0
  • The specification is written in YAML.
  • The specification adheres to Semver.

Identifiers

  • Fields etc. are written in camelCase.
  • Short identifiers are written as Id and not ID.

"Magic" numbers

Consistent identifiers

To make the examples in spec/examples more consistent, we use the following fixed identifiers. Exceptions:

  • lists with several different IDs
  • examples that are semantically different

If you use a new identifier, please make sure it differs in the first character since this makes it easier to read.

ID Value
caseId e89e107e-ed79-40e6-ad34-4e770f9df263
destinationId 879ee109-a690-4db8-ab32-424284184d7d
submissionId ce75a6b8-d72f-4b94-b09e-af6be35bc2ae
replyId b9715dcb-700e-44d9-802f-12b45bf9f8a3

Submission ce75a6b8-d72f-4b94-b09e-af6be35bc2ae

Attachments:

  • 879ee109-a690-4db8-ab32-424284184d7d
  • 2046f9f1-dc89-4440-9c24-c76a8f40d668

Reply b9715dcb-700e-44d9-802f-12b45bf9f8a3

Attachments:

  • 2d8cef0c-62e1-4936-925c-2da79377d29c
  • fa9e16fc-0cb1-4d14-9a9a-4130fa51083f

Callback locations

The callbacks are located at the locations where the callback URLs can be changed. Even though the callbacks might take place later. Rationale:

The OpenAPI spec in https://spec.openapis.org/oas/v3.1.0#callback-object says:

4.8.18 Callback Object

A map of possible out-of band callbacks related to the parent operation.

We interpret the "related" as: the callback URL that will be called is defined here.