REST guide
The REST styleguide, built from these sources, is available on https://www.belgif.be/specification/rest/api-guide/.
This styleguide is established by the REST design working group, which includes various participating Belgian government institutions. See the wiki for more information on the organization of the REST design working group and its meeting reports .
Reusable OpenAPI schemas
Reusable OpenAPI 2.0 and 3.0 data types are maintained in the belgif openapi-* GitHub repositories, organized per domain. Types in beta status are in the source code, but not part of the released artifacts. Apache Maven users can also download them from Maven Central.
domain | link |
---|---|
common | latest release |
problem | latest release |
time | latest release |
person | latest release |
person-identifier | latest release |
location | latest release |
organization-identifier | latest release |
employment-identifier | latest release |
money | latest release |
Guidelines to write the styleguide
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the REST styleguide are to be interpreted as described in RFC 2119. They are used in the rules defined throughout the REST styleguide wherever possible.
Examples must follow the following format:
.example title
====
<example, may use nested code blocks>
====
Rules must follow the following format:
[.rule, caption="Rule {counter:rule-number}: "]
.rule title
====
<the rule, using RFC 2119 key words>
====
Building the styleguide
The styleguide is built with Apache Maven.
With Maven installed, run mvn
in the root directory of the project.
The styleguide will be built in target/generated-docs/
and bundled as a zip in the target
directory.