search

belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
24 stars 4 forks source link

Add rule about using fedvoc naming #151

Open jpraet opened 9 months ago

jpraet commented 9 months ago

The rest-guide currently lists these as not covered:

Topics not covered in this guide:

  • Semantics of common business data (e.g. social security number, address, …​). These are managed by the REST Functional Working Group in the belgif fedvoc repository.
  • OpenAPI specifications for common data types can be found in the openapi-* GitHub repositories.

While I agree that the specifics of these topics are indeed out of scope for the rest-guide, I think it would be worthwhile to formalize that API providers should use the belgif types and fedvoc naming?

Rule: Use Belgif OpenAPI data types. [belgif-types]

API providers SHOULD use the standardized Belgif OpenAPI data types.

Rule: Use FedVoc vocabulary. [fedvoc]

API providers SHOULD follow the standard FedVoc vocabulary naming conventions.

pvdbosch commented 9 months ago

Rule on OpenAPI data types is already present: Rule: Common definitions for Belgian government institutions [oas-comdef]

Rule on FedVoc TODO, may with some guidance on how to map these to OpenAPI (e.g. property, Class ->types name); column inOpenAPI(yes/no)

jpraet commented 9 months ago

Rule on OpenAPI data types is already present: Rule: Common definitions for Belgian government institutions [oas-comdef]

Thanks, I overlooked that one somehow.