De front-end REST API is bedoeld als realtime koppeling met je website voor het uitvoeren van zoekopdrachten, opvragen van recommendations en andere functies.

Hosts

Het endpoint voor de frontend API is beschikbaar op twee verschillende domeinen. Ze bieden beide de zelfde functionaliteit maar zitten netwerktechnisch anders in elkaar:

• Gateway.tweakwisenavigator.com
  Dit endpoint beschikt over een realtime failover loadbalancer welke bij een storing in een datacenter automatisch terugvalt op een ander datacenter. Deze extra stap in het netwerk kan de latency verhogen van de requests.
• Gateway.tweakwisenavigator.net
  Via dit endpoint maakt de client een rechtstreekse verbinding met het dichtstbijzijnde datacenter en verlaagd de latency van requests. Wanneer er problemen zijn in een datacenter, bijvoorbeeld het falen van hardware, wordt het verkeer automatisch omgeleid naar een ander datacenter. Omdat deze omleiding is gebaseerd op DNS, kan het even duren voordat een omleiding overal is doorgevoerd.

We adviseren om als primair endpoint gebruik te maken van ‘gateway.tweakwisenavigator.net’ en een failover in de code in te bouwen naar ‘gateway.tweakwisenavigator.com’. Omdat de netwerken van deze twee endpoints volledig van elkaar gescheiden zijn kunnen we zo een extreem hoge uptime behalen.

Wanneer je liever gebruik maakt van één endpoint, adviseren we gebruik te maken van ‘gateway.tweakwisenavigator.com’ en niet van 'gateway.tweakwisenavigator.net'. Zo ben je minder afhankelijk van de eventuele vertraging in de DNS.

Instance key

Elk request bevat een instance key in het pad van de URL. Deze instance key is een unieke identificatie voor een Tweakwise Navigator instantie. Je kan deze key vinden in Navigator op https://navigator.tweakwise.com/endpoint. In de documentatie wordt duidelijk aangegeven waar in de URL de instance key geplaatst moet worden. Zoals bijvoorbeeld /navigation-search/{instancekey}.

Format

De API biedt ondersteuning voor XML & JSON. Standaard wordt een response altijd teruggegeven in XML. Als je liever gebruik wil maken van de JSON structuur is het mogelijk om de requests uit te breiden met de query string parameter format=json. Zoals bijvoorbeeld https://gateway.tweakwisenavigator.com/autocomplete/{instanceKey}/?tn_q=shoes&format=json

API documentation

De documentatie van alle beschikbare endpoints kan je hier vinden.

Voor elk afzonderlijk request wordt beschreven wat de mogelijke query string parameters zijn en welke daarvan verplicht zijn. Ook is het mogelijk een request uit te proberen door de Try it out knop te gebruiken. Zo krijg je een beter beeld van hoe de API zich gedraagt voor jouw specifieke instantie.

Groepering

De meeste calls zijn beschikbaar in twee versies: gegroepeerd en standaard. Een voorbeeld hiervan in de autocomplete call:

De grouped versie moet worden gebruikt wanneer er gebruik gemaakt wordt van de groepering feature in Navigator. 

Wat is een groepcode?

Welke API calls moet ik gebruiken als ik gebruik maak van een groepcode?

Commonly used endpoints

Voor de meest gebruikte endpoint verduidelijken we hieronder waar deze voor bedoeld zijn en wat de relatie is tussen je website en deze endpoints.

Autocomplete

Met het autocomplete endpoint is het mogelijk zoeksuggesties te koppelen. Een voorbeeld:

Het autocomplete endpoint geeft twee lijsten terug: Een lijst met producten en een lijst met zoeksuggesties. De lijst met producten maakt het mogelijk om productsuggesties te tonen op basis van het ingevoerde zoekwoord. De lijst met zoeksuggesties bevat de meest gezochte zoekwoorden. Deze kunnen als suggestie getoond worden op de website zoals in het voorbeeld hierboven. De specifieke documentatie is terug te vinden op http://developers.tweakwise.com/#/Autocomplete.

Navigation

Met het navigation endpoint is het mogelijk om een product lister pagina te vullen. De response bestaat uit een paar onderdelen:

• Een lijst met facetten
  Deze facetten hebben als doel dat de eindgebruiker de mogelijkheid heeft om te filteren op bijvoorbeeld merk of kleur. Een voorbeeld van een implementatie:

• Een lijst met producten
  Daarnaast bevat het resultaat een lijst met producten. Deze producten komen overeen met de huidige filters. Ook zijn deze producten gesorteerd volgens de relevantie in Navigator
• Een object met eigenschappen over het request
  Dit object bevat informatie als het aantal pagina’s, aantal producten, en de opties waarop gesorteerd kan worden.

Meer informatie over de technische implementatie kan je hier bekijken: http://developers.tweakwise.com/api/#/Navigation

Navigation Search

Naast de navigation-call is er ook een losse aanroep voor wanneer er gezocht moet worden op een zoekterm. Deze heet navigation-search. De specificaties zijn nagenoeg gelijk aan de navigation call met een paar uitzonderingen:

Er is een mogelijkheid om een extra zoekopdracht-filter te sturen, namelijk de querystring parameter: tn_q

De call geeft een extra eigenschap terug over het request, namelijk suggestedsearchterm. Wanneer de gebruiker een typefout maakt in de zoekopdracht, vervangen wij dit zoekwoord met een gecorrigeerde versie hiervan. Omdat we dit teruggeven in de aanroep is het mogelijk om aan de klant te tonen dat het zoekwoord is vervangen. Bijvoorbeeld: