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.

Sign up for GitHub

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

Update getting-started.md #531

Merged
merged 3 commits into from
Jan 13, 2022
Merged

Update getting-started.md #531

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff8d260
Update getting-started.md
melsk-r Jan 5, 2022
a47c2b0
Update getting-started.md
melsk-r Jan 10, 2022
70b1d97
Update getting-started.md
melsk-r Jan 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@ title: Getting Started
# Getting Started - BAG Huidige Bevragingen API

Om aan te sluiten kun je de volgende stappen doorlopen:
1. [Meld je aan bij het kadaster om toegang te krijgen tot de productieomgeving](#aanmelden-om-aan-te-sluiten)
2. [Bekijk de functionaliteit en specificaties](#functionaliteit)
3. [Probeer en test de API in de productie-omgeving](#probeer-en-test-de-api-in-de-productie-omgeving)
1. [Aanmelden](#aanmelden) om toegang te krijgen tot de acceptatie- en productieomgeving
2. Bekijk de [functionaliteit en specificaties](#functionaliteit-en-specificaties)
3. [Implementeer de API Client](#implementeer-de-api-client)
4. [Probeer en test de API](#probeer-en-test-de-api)


## Aanmelden om aan te sluiten
## Aanmelden
[Vraag een API key voor de productieomgeving aan](https://formulieren.kadaster.nl/aanvraag_bag_api_huidige_bevragingen_productie){:target="_blank"}. Testen doe je bij voorkeur in de productie-omgeving.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graag aanpassen in:' Testen doe je bij voorkeur in de testomgeving.'
Door testen in de productieomgeving worden ongecontroleerde aantallen requests ontvangen door nog niet gevonden fouten in de code die bijvoorbeeld loops veroorzaken. Hierdoor kan de beschikbaarheid van de API voor alle klanten onder druk komen te staan.
En idem als bij regel 8.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@NicoleKortoomsBAG ik herinner me dat we hebben afgesproken dat gebruikers in productie kunnen testen.

De acceptatieomgeving die ik gebruik voor nieuwe releases kunnen aansluiters niet gebruiken omdat die niet stabiel hoeft te zijn. Daarop komen niet volledig geteste nieuwe versies. Is er ook een testomgeving (eto) die altijd gelijk is aan productie waar aansluiters op kunnen testen? De aansluiting daarop (ten minste de url) moet dan ook worden toegevoegd aan de Getting started.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ongecontroleerde aantallen requests ontvangen door nog niet gevonden fouten in de code die bijvoorbeeld loops veroorzaken

Dat kan m.i. ook worden opgelost met rate limiting. Dat zouden we kunnen toevoegen als dat gewenst is. Zie https://geonovum.github.io/KP-APIs/API-strategie-extensies/#rate-limiting

Copy link
Contributor

@NicoleKortoomsBAG NicoleKortoomsBAG Jan 10, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Er mag getest worden in productie, we kunnen ook niet zien of iets een testgeval is of een productievraag, maar de voorkeur is om in de acceptatieomgeving te testen. Als straks rate en quota limiting wordt toegepast, is het voor de afnemer nog belangrijker dat hij test in de testomgeving. Anders verbruikt hij zijn quota door testen.
Als de afnemer iets specifieks wil testen en de testomgeving dat geval niet kent, zal dat enkele geval geen probleem zijn voor zijn quota. Als hij nieuwe code test en er zit een loop in, kan hij zijn eigen productie stilleggen. Door de client het direct goed in te laten richten, voorkomen we dat en dat hij later extra werk moet doen.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bij BRK hebben we naast productie acceptatieomgeving waar wij (Haal Centraal) nieuwe versies van de API op testen, en de ETO waar aansluiters op testen. De ETO is dus technisch altijd gelijk aan productie, maar bevat de data van de acceptatieomgeving. Dat is wat je voor BAG ook ook nodig hebt, wanneer je niet wilt dat op productie wordt getest.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ik heb hiervoor #533 aangemaakt


## Functionaliteit
## Functionaliteit en specificaties
Je kunt de Open API Specificaties (OAS3) van de API bekijken in [Swagger-formaat](./swagger-ui) of [Redoc](./redoc).

De (resolved) OAS3 is hier te downloaden: [openapi.yaml](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank" rel="noopener"}.
Expand Down Expand Up @@ -74,9 +74,23 @@ Verder zijn er nog een paar algemene functies die gelden voor alle bovenstaande
- Gebruik van paginering om het aantal zoekresultaten per zoekvraag te beperken. Met de **page** parameter kan een volgende pagina worden gevraagd. Met de **pageSize** parameter kan gekozen worden voor meer of minder zoekresultaten per pagina (standaard is 20, maximum is 100). Voor werking, zie feature [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"}
- Soms kan er een onderzoek lopen of een gegeven wel correct is. Er zijn dan twijfels over de juistheid van de geregistreerde waarde. De API levert deze waarde wel, maar neemt die velden dan op in **mogelijkOnjuist** met de waarde True.
- Sommige resources bevatten geometrie. De API ondersteunt op dit moment alleen het RD coördinatenstelsel (epsg:28992). Bij een aanvraag die geometrie teruglevert moet de request header **Accept-Crs** worden meegestuurd.
- Bij het zoeken van een pand op **locatie** moet de header **Content-Crs** worden meegestuurd. De API ondersteunt op dit moment alleen het RD coördinatenstelsel (epsg:28992).
- Bij het zoeken van een pand op **locatie** mag de header **Content-Crs** worden meegestuurd. Wanneer je deze header weglaat wordt default coördinatenstelsel RD (epsg:28992) gebruikt wat op dit moment ook het enige het coördinatenstelsel is dat de API ondersteunt.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Frank had al eerder aangegeven dat dit ook geldt voor het zoeken met de bbox. Die aanvulling is nog niet gedaan.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Die aanvulling staat in regel 78.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overheen gelezen. Excuus.

- Bij het zoeken naar panden en adresseerbare objecten kun je gebruik maken van bbox.
- [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08){:target="_blank"}, die soms [templated](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/uri-templating.feature){:target="_blank"} worden geleverd.

## Implementeer de API client
Client code kun jen genereren met de "[genereervariant](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank" rel="noopener"}" van de API-specificaties en een code generator. Een overzicht met codegeneratoren kun je vinden op [OpenAPI.Tools](https://openapi.tools/#sdk){:target="_blank" rel="noopener"}.

Deze repo bevat scripts waarmee je met [OpenAPI Generator](https://openapi-generator.tech/){:target="_blank" rel="noopener"} client code kunt genereren in JAVA, .NET (Full Framework & Core) en Python. De makkelijkste manier om de code generatie scripts te gebruiken, is door deze repo te clonen. Na het clonen kun je met `npm install` de benodigde packages installeren en kun je met npm run <script naam> één van de volgende scripts uitvoeren:
- oas:generate-java-client (voor JAVA client code)
- oas:generate-netcore-client (voor .NET Core client code)
- oas:generate-net-client (voor .NET Full Framework client code)
- oas:generate-python-client (voor Python client code)

Een lijst met andere ondersteunde generator opties kun je vinden in de [Generators List](https://openapi-generator.tech/docs/generators){:target="_blank" rel="noopener"} van OpenAPI Generator.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Een lijst met andere ondersteunde generator opties kun je vinden...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aangepast.

Note. De prerequisite van OpenAPI Generator is JAVA. Je moet een JAVA runtime installeren voordat je OpenAPI Generator kunt gebruiken

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Je moet een JAVA runtime installeren voordat je OpenAPI Generator kunt gebruiken.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aangepast.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'De prerequisite OpenAPI Generator is JAVA' aanvullen naar 'De prerequisite van OpenAPI Generator is JAVA'?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aangepast

## Probeer en test de API
De werking van de API is het makkelijkst te testen met behulp van [Postman](https://www.getpostman.com/){:target="_blank"}.
De [openapi.yaml](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank"} kun je importeren als project, waarna de verschillende requests worden ingeladen die deze API ondersteunt.
Expand Down