Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API-04 design rule herschreven op basis van issue #419 #118

Open
wants to merge 5 commits into
base: develop
Choose a base branch
from

Conversation

mrtn78
Copy link
Member

@mrtn78 mrtn78 commented Nov 17, 2021

Resolves Geonovum/KP-APIs#419

API-04 design rule herschreven op basis van issue #419

Kopie van het issue:
Originele bericht van Provincie Zuid-Holland:

API-04: Define interfaces in Dutch unless there is an official English glossary available
Dit is niet te hanteren in een situatie waarin die glossary er nog niet is. Twee situaties:

  • een open source ontwikkeltraject waarin je nog niet beschikt over een engelstalige glossary maar toch de code internationaal wilt delen om de community zo groot mogelijk te maken. Engels is dan de te hanteren standaardtaal.
  • interfaces met een COTS toepassing. De leverancier is internationaal georiënteerd en hanteert Engels als voertaal.

Interpretatie vanuit Logius voor aanpassing van de ADR:

  • we gaan duidelijk onderscheid maken tussen het hergebruik van bestaande glossary/schema en het ontwikkelen van een eigen (nieuwe) glossary
  • toevoegen dat samenwerking met COTS (Commercial Off The Shelf ) software leveranciers ook een reden kan zijn om engels te hanteren.

@mrtn78 mrtn78 added help wanted Extra attention is needed Scope: Klein Kleine wijzigingen met beperkte scope Status: Afgewezen Het voorstel is afgewezen en kan opnieuw in behandeling worden genomen na aanpassing. Status: Uitwerking door derden Het voorstel wacht op uitwerking door een externe partij. Type: Wijziging Inhoudelijke wijziging op een standaard Overleg: TO API Te agenderen voor het Technisch Overleg ADR - API Design Rules labels Jul 6, 2023
@mrtn78 mrtn78 marked this pull request as draft July 20, 2023 08:50
@TheBonheurs
Copy link
Member

TheBonheurs commented Oct 18, 2024

  • Waarom is er gekozen voor de term Glossary? Zou Specification niet een betere term zijn?
  • Zijn het eigenlijk niet gewoon naming conventions? Zal ik deze term in verwerken?
  • De structuur van de zin "define in Dutch unless English exists" matcht niet zo lekker met de achterliggende intentie volgens mij. Wij zijn voorstander van zoveel mogelijk Engelse definities vanwege interoperabiliteit met de bestaande API dev community, zie bv. Google API design docs. Ik zou dan de regel zo formuleren → "define in English/adhere to English conventions unless there are none available. Fallback on dutch otherwise." Thoughts?

@mrtn78
Copy link
Member Author

mrtn78 commented Oct 24, 2024

Aandachtspunten:

  • official kan eruit.
  • interfaces specifieker benoemen tot resources en attributes
  • term Glossary blijft
  • onderzoeken hoe dit samenhangt met de module naming conventions

@TheBonheurs TheBonheurs marked this pull request as ready for review October 28, 2024 10:47
@TheBonheurs
Copy link
Member

In line with design rule <a href="#/core/interface-language">/core/interface-language</a>, the OAS document (e.g. descriptions and examples) SHOULD be written in Dutch. If relevant, you MAY refer to existing documentation written in English.

willen wij ook deze rule aanpassen?
dat was ook een opmerking van Hugo volgens mij, dat de OAS gewoon in engels kon blijven.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed Overleg: TO API Te agenderen voor het Technisch Overleg ADR - API Design Rules Scope: Klein Kleine wijzigingen met beperkte scope Status: Afgewezen Het voorstel is afgewezen en kan opnieuw in behandeling worden genomen na aanpassing. Status: Uitwerking door derden Het voorstel wacht op uitwerking door een externe partij. Type: Wijziging Inhoudelijke wijziging op een standaard
Projects
None yet
Development

Successfully merging this pull request may close these issues.

API-4 niet duidelijk in verschillende situaties - Feedback Publieke Consultatie
2 participants