Webservices

Uit G!ds
Ga naar: navigatie, zoeken

Alle functionaliteit die de G!DS biedt wordt aangeboden door SOAP webservices. Als transportprotocol wordt HTTPS gebruikt waardoor een beveiligde verbinding tot stand wordt gebracht. Over deze verbinding worden alle gegevens zonder overige encryptie verstuurd.

Documentation caution.png Om soap over https te kunnen gebruiken is het in sommige omgevingen nodig om extra modulen aan te zetten, bv. Apache/PHP SSL module

Een volledig overzicht van alle webservices die worden aangeboden is te vinden op https://webservices.gids2.nl (productie) en https://gids-webservices.acc1.bibliotheek.nl/ (zandbak)

Alle voor ontwikkelaars relevante webservices zijn verzameld in de gmlservice:

De resultaten van deze functies zijn opgemaakt in GML. De gewenste GML-versie is onderdeel van elk request. Als deze niet wordt opgegeven wordt GML versie 1 aangenomen.

De meeste functies worden in 2 varianten aangeboden namelijk de standaard en de overzicht-variant. De standaardvarianten geven volledige objecten terug met alle informatie die in de G!DS aanwezig is. Meestal is het niet nodig om bij een zoekresultaat de volledige gegevens te retourneren. In veel gevallen is dit slechts verspilling van dataverkeer tussen G!DS en website, vaak is de naam en enkele basisgegevens voldoende. In deze gevallen kan er beter gebruik gemaakt worden van de overzicht-functies. Deze geven minder gegevens terug (dus minder dataverkeer) en hebben ook minder database acties nodig om alle gegevens bij elkaar te zoeken, dus de functies zijn sneller.

Profielen

haalBeschikbareProfielen

Deze call geeft een overzicht terug met alle profielen waarin met de gebruikte websiteaccount gezocht mag worden. Details van deze profielen kunnen opgehaald worden met haalProfiel.

haalProfielenVanOrganisatie

Deze call geeft een overzicht terug met alle profielen van de betreffende organisatie. Details van deze profielen kunnen opgehaald worden met haalProfiel.

haalProfiel

Met deze call kunnen de details van een profiel opgevraagd worden. Deze details vormen de bron van de organisatieFilterQuery, productFilterQuery en hyperlinkFilterQuery.

Zoeken

Functie aanroep

In principe hebben alle zoekfuncties dezelfde functie aanroep, ze verschillen slechts in de response. Daarom wordt hier slechts één functie aanroep behandeld. Enige uitzondering is zoek(Overzicht)ProductenVanOrganisatie, deze verwacht een organisatieId in plaats van een profielId.

zoekProducten

Zie zoekOverzichtOrganisaties

zoekOrganisaties

Zie zoekOverzichtOrganisaties

zoekHyperlinks

Zie zoekOverzichtOrganisaties

zoekProductenVanOrganisatie

Zie zoekOverzichtOrganisaties

zoekOverzichtProducten

Zie zoekOverzichtOrganisaties

zoekOverzichtHyperlinks

Zie zoekOverzichtOrganisaties

zoekOverzichtProductenVanOrganisatie

Zie zoekOverzichtOrganisaties

zoekOverzichtOrganisaties

Voorbeeld van een overzichtOrganisaties-zoekvraag:

  1. <zoekOverzichtOrganisaties>
  2.   <query>Organisatie.publieksNaam:bibliotheek~ Assen^10</query>
  3.   <profielId>1</profielId>
  4.   <sorteerVelden>
  5.     <SorteerVeld> 
  6.       <richting>ASC</richting>
  7.       <veld>PUBLIEKSNAAM</veld>
  8.       <volgnummer>1</volgnummer>
  9.     </SorteerVeld>
  10.   </sorteerVelden> 
  11.   <profielBeperkendFilter>Organisatie.hoofdContactGegevens.bezoekAdres.postcode4:[9000 TO 9999]</profielBeperkendFilter> 
  12.   <maxResultaten>100</maxResultaten>
  13.   <startIndex>0</startIndex>
  14. </zoekOverzichtOrganisaties>

Beschrijving van de zoekvraag argumenten

  • query
    Dit is de feitelijke zoekopdracht. De syntax hiervoor wordt uitgebreid behandeld in de zoekmachinehandleiding.
  • profielId
    Het profielnummer van het profiel dat in de G!DS wordt beheerd.
  • sorteerVelden
    Een lijst met velden waarop de resultaten gesorteerd worden. Er kan dus op meerdere velden worden gesorteerd, bijvoorbeeld eerst op WOONPLAATS en dan op MATCH.
    Een SorteerVeld bestaat uit de volgende onderdelen:
    • SorteerVeld
      • richting
        De sorteerrichting heeft een van de volgende waarden:
        ASC om oplopend te sorteren.
        DESC om aflopend te sorteren.
      • veld
        MATCH - Sorteer op de relevantie van de query
        ID - Sorteer op het organisatieId, productId of hyperlinkId
        AANMAAKDATUM - Sorteer op de aanmaakdatum
        WIJZIGINGSDATUM - Sorteer op de datum van laatste wijziging
        PUBLIEKSNAAM - Sorteer op de publieksnaam (ook gebruiken voor hyperlink-naam)
        ORGANISATIENAAM - Sorteer op de publieksnaam van de organisatie
        AFKORTING - Sorteer op de afkorting (alleen bij zoeken op organisaties bruikbaar)
        ETIKETNAAM - Sorteer op de etiketnaam (alleen bij zoeken op organisaties bruikbaar)
        SOORTNAAM - Sorteer op de naam van de organisatie/productsoort
        SUBNAAM - Sorteer op de subnaam (alleen bij zoeken op organisaties bruikbaar)
        VOLLEDIGE_NAAM - Sorteer op het veld ‘volledigeNaam’
        POSTCODE - Sorteer op de postcode van het bezoekadres van de hoofdlocatie
        WOONPLAATS - Sorteer op de woonplaats in het bezoekadres van de hoofdlocatie
        AGENDADATUM - Sorteer op de datum die is opgegeven in een Agenda-veld. Producten zonder agenda komen achteraan te staan bij ASC, vooraan bij DESC (alleen bij zoeken op producten bruikbaar)
      • volgnummer
        Een uniek nummer in de lijst met sorteervelden, benodigd om aan te geven in welke volgorde de sorteervelden moeten worden toegepast. Hoe lager het nummer, hoe hoger de prioriteit van het sorteerveld.
  • profielBeperkendFilter
    Een niet-verplicht veld waarmee de uitvoer van een profiel beperkt kan worden. Er wordt dan alleen gezocht in de items die voldoen aan de eigenschappen van het profiel en voldoen aan het profielBeperkendFilter. De syntax van een profielBeperkendFilter is gelijk aan de syntax van een zoekopdracht. Zie voor een uitgebreide beschrijving de [Handleiding - Zoekmachine]. Het grote verschil tussen de query en het profielBeperkendFilter is dat het filter geen invloed heeft op de sortering van de zoekresultaten (en dus sneller werkt).
  • maxResultaten
    Het maximale aantal resultaten dat geretourneerd zal worden. Bedoeld voor paginering. Het maximum is 1000.
  • startIndex
    De positie in de lijst met resultaten vanaf waar geretourneerd moet worden. Bedoeld voor paginering. Het eerste item heeft startIndex 0.
  • gmlVersie
    De versie GML waarin het resultaat opgemaakt moet worden. Als deze niet wordt opgegeven wordt GML versie 1 gebruikt.
Documentation note.png Hoewel niet alle parameters verplicht zijn, is het wel noodzakelijk om de parameters in de juiste volgorde (zie wsdl) aan te bieden


Zoekvraag response

Hier een voorbeeld van de response op een zoekopdracht. Voor de leesbaarheid zijn de gegevens iets vereenvoudigd en de namespaces weg gelaten.

  1. <zoekOverzichtOrganisatiesResponse>
  2.    <return>
  3.       <bedoeltUQuery>+(+$/Organisatie/publieksNaam:bibliotheek~0.5 +((alias:organisatie extendedAlias:organisatie)~1)) +ass^10.0</bedoeltUQuery>
  4.       <organisaties>
  5.          <string><![CDATA[<OverzichtOrganisatie>...</OverzichtOrganisatie>]]></string>
  6.          <string><![CDATA[<OverzichtOrganisatie>...</OverzichtOrganisatie>]]></string>
  7.          <string><![CDATA[<OverzichtOrganisatie>...</OverzichtOrganisatie>]]></string>
  8.          <string><![CDATA[<OverzichtOrganisatie>...</OverzichtOrganisatie>]]></string>
  9.          <string><![CDATA[<OverzichtOrganisatie>...</OverzichtOrganisatie>]]></string>
  10.       </organisaties>
  11.       <query>Organisatie.publieksNaam:bibliotheek~ Assen^10</query>
  12.       <resultCount>11</resultCount>
  13.       <rewrittenQuery>+(+$/Organisatie/publieksNaam:bibliotheek~0.5 +((alias:Organisatie extendedAlias:Organisatie)~1)) +ass^10.0</rewrittenQuery>
  14.    </return>
  15. </zoekOverzichtOrganisatiesResponse>


In de array met organisaties zitten de Gml-documenten van de overzicht-organisaties die aan de zoekvraag voldoen. In het veld resultCount wordt het aantal resultaten gegeven dat voldoet aan de zoekvraag (dit getal kan gebruikt worden om het aantal pagina's met resultaten te bepalen). Bekijk voor een uitleg van de opbouw van de verschillende Gml-documenten de pagina Gml.

Websitehelper-webservices

In de websitehelper-service zitten enkele handige functies voor websitebouwers die anders complexe operaties vereenvoudigen.

Kalenderfuncties

Met de standaard zoekfunctionaliteit van de G!ds is het niet eenvoudig om goede kalenders of agenda overzichten te genereren omdat elke product slechts één keer wordt terug gegeven met de volledige agenda. Als er een kalender of agenda overzicht moet worden weergegeven is het vaak handiger om de evenementen chronologisch (en soms dus dubbel) te krijgen. De kalender functies voorzien hierin.

haalEvenementenKalender

Deze functie is handig als een een kalender overzicht moet worden weergegeven met het aantal evenementen per datum.

De parameters zijn:

  • query (optioneel): een zoekvraag waaraan de evenementen moeten voldoen
  • profielId: het profielId van het profiel waar de evenementen in gedefinieerd zijn
  • vanDatum: de begindatum van de kalenderweergave
  • totDatum: de einddatum van de kalenderweergave

Het resultaat is een lijst met data en het aantal evenementen op die dag, bijvoorbeeld:

  1. <EvenementenKalenderInfo>
  2.   <aantalEvenementen>12</aantalEvenementen>
  3.   <datum>2009-06-12T00:00:00+02:00</datum>
  4. </EvenementenKalenderInfo>

haalEvenementenKalenderMetProducten

haalEvenementenKalenderMetProducten

De functies haalEvenementenKalenderMetProducten en haalEvenementenKalenderMetOverzichtProducten zijn gemaakt om een chronologisch overzicht te maken van evenementen. De functies vereisen dezelfde parameters als haalEvenementenKalender met als aanvulling dat paginering mogelijk is d.m.v. maxResultaten en startIndex. Het resultaat is een lijst met EvenementenKalenderProductInfo-elementen met elk een datumTijd en een productId. Het productId verwijst naar een product in de lijst met producten verderop in het antwoord. Deze lijst bevat de unieke producten zodat een evenement dat op meerdere dagen voorkomt maar één keer volledig wordt teruggegeven.

Het resultaat zou als volgt kunnen zijn:

  1. <evenementenKalender>
  2.   <EvenementenKalenderProductInfo>
  3.     <datumTijd>2009-07-10T10:00:00+02:00</datumTijd>
  4.     <productId>112456</productId>
  5.   </EvenementenKalenderProductInfo>
  6.   <EvenementenKalenderProductInfo>
  7.     <datumTijd>2009-07-11T10:00:00+02:00</datumTijd>
  8.     <productId>112456</productId>
  9.   </EvenementenKalenderProductInfo>
  10.   <producten>
  11.     <string><ProductGml productId="112456">...</ProductGml></string>
  12.   </producten>
  13. </evenementenKalender>

Detail-webservices

haalHyperlink

Deze call verwacht een hyperlinkId.
Retourneert de gevraagde hyperlink in de opgegeven GML-versie

haalOrganisatie

Deze call verwacht een organisatieId.
Retourneert de gevraagde organisatie in de opgegeven GML-versie

haalOrganisaties

Deze call verwacht een lijst met organisatieIds
Retourneert een lijst met de gevraagde organisaties in de opgegeven GML-versie

haalProduct

Deze call verwacht een productId.
Retourneert het gevraagde product in de opgegeven GML-versie

haalProducten

Deze call verwacht een lijst met productIds
Retourneert een lijst met de gevraagde producten in de opgegeven GML-versie

haalProductenVanOrganisatie

Deze call verwacht een organisatieId.
Retourneert een lijst met de producten van de opgegeven organisatie in de opgegeven GML-versie

Een voorbeeld van de response van de haalOrganisatie-functie:

  1. <haalOrganisatieAlsGmlResponse>
  2.   <return><![CDATA[<OrganisatieGml ... </OrganisatieGml>]]></return>
  3. </haalOrganisatieAlsGmlResponse>