generated from ConductionNL/product-website-template
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
31 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,39 @@ | ||
| # Integratie | ||
|
|
||
| OpenWoo.app is essentie een koppelvlak waar aan de bovenkant meerdere weergaven of user interfaces op kunnen worden gekoppeld en aan de onderkant meerdere bronnen ontsloten. | ||
| Deze pagina is bedoeld voor developers die meer info proberen op tehalen over de OpenWoo.app koppeling of hier al mee aan de slag willen. | ||
|
|
||
| Als er tijdens of na het lezen zijn nog vragen zijn, neem een kijkje op de [FAQ](./FAQ.md). | ||
|
|
||
| ## Wat is OpenWoo.app | ||
|
|
||
| OpenWoo.app is in essentie een API koppelvlak waar aan de bovenkant meerdere weergaven of user interfaces (front-ends) op kunnen worden gekoppeld en aan de onderkant meerdere bronnen ontsloten. Als u meer wilt weten over OpenWoo.app kunt u meer lezen op [https://openwoo.app](https://openwoo.app). | ||
|
|
||
| > **Hulp nodig?** | ||
| > | ||
| > Hiervoor hebben we een appart [slack kanaal](https://samenorganiseren.slack.com/archives/C067Q3UE9F0) binnen commonground. We helpen je daar graag verder. | ||
| ## Het koppelen van een user interface | ||
|
|
||
| Als u als organisatie of leverancier OpenWoo.app wilt koppelen aan een huidige interface (bijvoorbeeld door de resultaten uit uw gemeente in uw website te integereren) and kunt u daarvoor gebruikmaken van de OpenWoo.app API. | ||
| Als u als organisatie of leverancier OpenWoo.app wilt koppelen aan een huidige interface (bijvoorbeeld door de resultaten uit uw gemeente in uw website te integereren) dan kunt u daarvoor gebruikmaken van de OpenWoo.app API. Wij kunnen de bron synchroniseren naar ons koppelvlak en dan zal via de API uw resultaten zichtbaar zijn die u dan via uw user interface zou kunnen bevragen en gebruiken. | ||
|
|
||
| ### Locatie en Authenticatie | ||
|
|
||
| U vindt de API op [https://api.gateway.commonground.nu/api/publicaties](https://api.gateway.commonground.nu/api/publicaties). Voor het stellen van zoekvragen is géén authenticatie vereist (het doel van OpenWOO.app is immers het verspreiden van openbare informatie). Er is echter wel sprake van throttling op response tijden (de API reageert langzamer) en rate-limiting (het aantal bevragingen per minuut en uur zijn beperkt) zonder authenticatie. Ook zijn alleen de GET (ophalen) acties toegestaan zonder authenticatie. | ||
| De API staat online en is beschikbaar op [https://api.gateway.commonground.nu/api/publicaties](https://api.gateway.commonground.nu/api/publicaties). Voor het stellen van zoekvragen is géén authenticatie vereist (het doel van OpenWOO.app is immers het verspreiden van openbare informatie). Er is echter wel sprake van throttling op response tijden (de API reageert langzamer) en rate-limiting (het aantal bevragingen per minuut en uur zijn beperkt) zonder authenticatie. Ook zijn alleen de GET (ophalen) acties toegestaan zonder authenticatie. | ||
|
|
||
| Als u vanuit uw casus een API nodig heeft zonder throttling, ratelimit of namens een organisatie wijzigingen wilt doen (POST,PUT,DELETE) dan kunt u een mail sturen naar <[email protected]>. | ||
| Als u vanuit uw casus een API nodig heeft zonder throttling, ratelimit of namens een organisatie wijzigingen wilt doen (en POST, PUT, DELETE API requests wilt maken) dan kunt u een mail sturen naar <[email protected]>. | ||
|
|
||
| ### Documentatie | ||
|
|
||
| Voor de API is een [redoc documentatie](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/oas.yaml) beschikbaar met voorbeelden van de verschillende API endpoints, calls en resultaten. Omdat de API daarnaast kan worden gebruikt zonder authenticatie is deze ook goed te beproeven via onze [Postman collectie](). We raden developers van ook van harte aan om aan de hand van deze collectie te spelen en ontwikkelen. | ||
| Voor de API is een [redoc documentatie](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/oas.yaml) beschikbaar met voorbeelden van de verschillende API endpoints, calls en resultaten. Omdat de API daarnaast kan worden gebruikt zonder authenticatie is deze ook goed te beproeven via onze [Postman collectie](). We raden developers van ook van harte aan om aan de hand van deze collectie te spelen en te ontwikkelen. | ||
|
|
||
| ### Voorbeelden | ||
|
|
||
| In het merendeel van de gevallen zult u een zoekvraag willen uitvoeren binnen de Woo publicaties van OpenWoo.app, het endpoint daarvoor is: <https://api.gateway.commonground.nu/api/publicaties>. Er zijn 4 voor de hand liggende zoekparameters waarmee gezocht wordt (overige opties vind u terug in de [Redoc documentatie]()). | ||
| In het merendeel van de gevallen zult u een zoekvraag willen uitvoeren binnen de Woo publicaties van OpenWoo.app, het endpoint daarvoor is: <https://api.gateway.commonground.nu/api/publicaties>. Er zijn 4 voor de hand liggende zoek query parameters waarmee gezocht wordt (overige opties vind u terug in de [Redoc documentatie]()). | ||
|
|
||
| 1. Op een of meerdere zoek woorden, b.v. `_search=test` | ||
| 2. Op organisatie, dit gaat aan de hand van OIN (de volledige OIN lijst vind u [hier](https://oinregister.logius.nl/oin-register)) b.v. `oin=00000001001299992000` | ||
| 3. Op categorie, `categorie=Convenant` | ||
| 4. Op datum, Hierbij kunt u een begin en eindatum opgeven om een periode (bijvoorbeeld jaar) te doorzoeken publicatiedatum[after]=2022-12-31T23:59:59Z&publicatiedatum[before]=2024-01-01T00:00:00Z& | ||
| 1. Op een of meerdere zoek woorden, b.v. `?_search=test` | ||
| 2. Op organisatie, dit gaat aan de hand van OIN (de volledige OIN lijst vind u [hier](https://oinregister.logius.nl/oin-register)) b.v. `?organisatie.in=00000001001299992000` | ||
| 3. Op categorie, `?categorie=Convenant` | ||
| 4. Op datum, Hierbij kunt u een begin en eindatum opgeven om een periode (bijvoorbeeld jaar) te doorzoeken `?publicatiedatum[after]=2022-12-31T23:59:59Z&publicatiedatum[before]=2024-01-01T00:00:00Z&` | ||
|
|
||
| ````cli | ||
| GET 'https://api.gateway.commonground.nu/api/publicaties?extend[]=all&_search=Afvalwaterakkoord&_order[publicatiedatum]=desc&_limit=12&_page=1' | ||
|
|
@@ -137,28 +143,34 @@ Response | |
| ```` | ||
|
|
||
| ### Metadata | ||
| De kern gegevens van een WOO publicatie zitten in het metadata object, de inhoud van dit object is 'semi' vrij, hij kan per publicatie `categorie` verschillen. Daarnaast zijn er een paar algemene properties die altijd kunnen voorkomen in de metadata | ||
| De kern gegevens van een Woo publicatie zitten in het metadata object, de inhoud van dit object is 'semi' vrij, hij kan per publicatie `categorie` verschillen. Daarnaast zijn er een paar algemene properties die altijd kunnen voorkomen in de metadata | ||
|
|
||
| #### Algemene properties | ||
|
|
||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------| | ||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |-----------------------|---------------|--------------|-----------------------| | ||
| | besluitdatum | Nee | Detailpagina | String in date format | | ||
| | ontvangstdatum | Nee | Detailpagina | String in date format | | ||
| | informatieverzoek | Nee | Detailpagina | Bijlage object | | ||
| | besluit | Nee | Detailpagina | Bijlage object | | ||
| | inventarisatielijst | Nee | Detailpagina | Bijlage object | | ||
| | termijnoverschrijding | Nee | Detailpagina | String | | ||
|
|
||
|
|
||
| #### Convenanten | ||
|
|
||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------| | ||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |-----------------------|---------------|--------------|-----------------------| | ||
|
|
||
| #### Woo verzoeken | ||
|
|
||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------| | ||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |-----------------------|---------------|--------------|-----------------------| | ||
|
|
||
| #### Klachten | ||
|
|
||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------| | ||
| | Property | Verplicht | Gebruik | Toegestane waardes | | ||
| |-----------------------|---------------|--------------|-----------------------| | ||
|
|
||
| ### Spelregels | ||
|
|
||
|
|
||