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 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 | release | OpenAPI |
|---|---|---|
| common | latest release | OpenAPI (dev version) |
| problem | latest release | OpenAPI (dev version) |
| time | latest release | OpenAPI (dev version) |
| person | latest release | OpenAPI (dev version) |
| person-identifier | latest release | OpenAPI (dev version) |
| location | latest release | OpenAPI (dev version) |
| organization-identifier | latest release | OpenAPI (dev version) |
| employment-identifier | latest release | OpenAPI (dev version) |
| money | latest release | OpenAPI (dev version) |
The keywords "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, <rule-id>]
.rule title
====
<the rule, using RFC 2119 key words>
====
<rule-id> should be a shorthand textual identifier for the rule of max 10 characters long. Dashes can be used as word separator.
An anchor of format #rule-<rule-id> to each rule is made. When changing a , an inline asciidoc anchor [[rule-<rule-id>]] should be placed at the start of the rule text so the old anchor still works.
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 guide/target/generated-docs/ and bundled as a zip in the target directory.