rest-guide
rest-guide copied to clipboard
belgif
REST Guidelines of Belgian government institutions
We're regularly encountering errors when oneOf or discriminators are being used. * OpenAPI document authors sometimes mistakenly assume that the oneOf subschema types are part of the JSON message; and...
OpenAPI allows enum values that are invalid to the rest of a schema, e.g. integer enum values for string types. In OpenAPI such contradiction is allowed; the most restrictive constraint...
Add a guideline that operationId MUST be present for each operation: * This operationId is used by code generation tools; using it will avoid warnings and bad method names: `Empty...
In builds of rest-guide and the openapi-* projects, we have some deprecation warnings in the builds about * https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/ => will be problem in Spring 2024 * https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/ For rest-guide,...
I often find that the names of properties used in the "required" array haven't been kept in sync with their defined names. For example: ```YAML type: object properties: nameNew: type:...
The problem RFC explicitly states in https://www.rfc-editor.org/rfc/rfc9457.html#section-3.1.4: > Consumers SHOULD NOT parse the "detail" member for information; extensions are more suitable and less error-prone ways to obtain such information. Could...
Open source the styleguide validation tool developed at Smals, in new repo under belgif. Would be published as Apache License 2.0.
REST API designers sometimes struggle to represent resources that are defined by a composite business key with a proper URI. E.g. in case of a monthly declaration of a an...
At CBSS we package our openapi definitions as a zip file with this folder structure: * belgif * common * v1 * common-v1.yaml * problem * v1 * problem-v1.yaml *...