Handleiding Niki API Auteurs: Haike Zegwaard (Fundament All Media) Marcel Mulder (Fundament All Media) Martin Poelman (Fundament All Media) Datum: 24 juni 2016 Niki: 3.30.0
Inhoud 1 Inleiding... 3 2 OAuth... 4 2.1 OAuth token... 4 2.2 Webservice account...4 2.3 Stappenplan token aanvragen... 4 2.4 Specificaties Niki OAuth provider... 4 3 REST API... 6 4 Demo API key... 7 5 OAuth test account... 8 6 Ontwikkelaar modus... 9 7 Omgevingen... 10 7.1 Acceptatie en test omgeving... 10 7.2 Live (productie) omgeving... 10 8 Referenties... 11 Handleiding Niki API 2 / 11
1 Inleiding Om de projectinformatie uit Niki toegankelijker te maken is, naast de bestaande SOAP webservice, een REST API gebouwd. Dit zorgt ervoor dat een koppeling met Niki technisch eenvoudiger te implementeren is met technieken die tegenwoordig alom gebruikt worden. Daarnaast wordt de performance van een dergelijke koppeling aanzienlijk verbeterd doordat niet langer alle projectinformatie ineens wordt opgehaald, maar alleen de relevante gegevens. Daarnaast is een beveiligingssysteem ingebouwd middels de OAuth 1.0 standaard. Gegevens worden in JSON formaat gecommuniceerd in plaats van XML. Handleiding Niki API 3 / 11
2 OAuth De Niki API maakt gebruik van OAuth voor de autorisatie. OAuth is een open standaard die tegenwoordig veelvuldig wordt toegepast. Middels OAuth moet een token worden aangevraagd. Met dit token wordt toegang verkregen tot de Niki API. 2.1 OAuth token Niki heeft een OAuth provider waar een token aangevraagd kan worden. Om een token aan te vragen moet er op de ingelogd worden met een webservice account. Dit zijn Niki accounts waarvan de inlognaam begint met data... of content... 2.2 Webservice account Niki webservice accounts worden gebruikt voor de Niki SOAP webservice en voor het aanvragen van een OAuth token voor de Niki API. Een webservice account bestaat uit een inlognaam en een wachtwoord. Niki abonnees kunnen via het Niki projectbeheer (admin.niki.nl) webservice accounts aanmaken. Dit kan via het menuitem data selectie webservice. De abonnee kan daarbij zelf een selectie van projecten maken die toegankelijk zijn met het account. Als er projecten van meerdere Niki abonnees moeten worden ontsloten dan kan de Stichting LNP een content afnemer account aanmaken. 2.3 Stappenplan token aanvragen Het aanvragen van een token bestaat uit een aantal stappen: 1. Het aanvragen van een tijdelijk token bij de Niki OAuth provider. 2. Het autoriseren van het tijdelijke token. Hiervoor toont de Niki OAuth provider een inlogpagina. Hier kan ingelogd worden met een webservice account. Vervolgens moet de token aanvraag worden bevestigd. 3. Het omzetten van het tijdelijke token naar een definitief token. Door gebruik te maken van een OAuth 1.0 client zijn deze stappen eenvoudig te automatiseren. 2.4 Specificaties Niki OAuth provider De Niki OAuth provider implementeert OAuth versie 1.0 token aanvragen token autoriseren /oauth/requesttoken /oauth/authorization token bevestigen consumer key /oauth/accesstoken domeinnaam van de website waarop de Niki API wordt aangesproken Handleiding Niki API 4 / 11
consumer secret signature method IMPLEMENT_SECRET HMAC-SHA1 De consumer key is de domeinnaam van de website waarop de Niki API wordt aangesproken. Dit is alleen de (sub)domeinnaam zonder http:// en zonder pad. Betreft het geen website gebruik dan een combinatie van bedrijfsnaam en applicatienaam. De consumer secret wordt mogelijk nog gewijzigd. Dat heeft geen effect op reeds uitgegeven tokens. Handleiding Niki API 5 / 11
3 REST API Een lijst met alle resources (mogelijke API calls) is beschreven op de documentatie pagina van de API. Deze pagina is beschikbaar op /apidocs De geretourneerde data is in JSON formaat (met uitzondering van binaire data zoals afbeeldingen, brochures en plattegronden). Met uitzondering van de binaire data kunnen API resources alleen opgevraagd worden middels een geldige oauth_token parameter. Voorbeeld: Voor een lijst met alle projecten die voor de gebruiker beschikbaar zijn, gebruik: /projects/mine?oauth_token= (/apidocs/resources/projects-mine.html) Hiermee worden referenties naar alle projecten van de gebruiker opgehaald. Dit zal resulteren in een lijst met naam en link-paren als volgt: [ { name : voorbeeldproject1, link : /projects/7/de3446232 }, { name : voorbeeldproject2, link : /projects/8/fe54545 } ] Vervolgens kan de link van een project worden aangeroepen (uiteraard met OAuth token) om de specifieke informatie over het project te krijgen. In deze informatie zijn ook weer links opgenomen naar de afbeeldingen, de woningtypen en de betrokken partijen. Handleiding Niki API 6 / 11
4 Demo API key Voor de API op de Niki acceptatieomgeving is een demo API key beschikbaar. Met deze API key zijn een aantal demo projecten op te vragen. De demo projecten zijn te gebruiken voor het testen en ontwikkelen met de Niki API. De demo api key is: 9a96c922-d586-4113-82c4-7994a008022a Voorbeeld url's: http://api.acc.niki.nl/projects/mine?oauth_token=9a96c922-d586-4113-82c4-7994a008022a http://api.acc.niki.nl/projects/325/2dvbvdemo_for_sale?oauth_token=9a96c922- d586-4113-82c4-7994a008022a http://api.acc.niki.nl/images/517737/normal http://api.acc.niki.nl/projects/325/2dvbvdemo_for_sale/housetypes? oauth_token=9a96c922-d586-4113-82c4-7994a008022a http://api.acc.niki.nl/projects/325/2dvbvdemo_for_sale/developers? oauth_token=9a96c922-d586-4113-82c4-7994a008022a http://api.acc.niki.nl/projects/325/2dvbvdemo_for_sale/brokers? oauth_token=9a96c922-d586-4113-82c4-7994a008022a http://api.acc.niki.nl/projects/325/2dvbvdemo_for_sale/involvedparties? oauth_token=9a96c922-d586-4113-82c4-7994a008022a Handleiding Niki API 7 / 11
5 OAuth test account Voor de OAuth provider is ook een testaccount beschikbaar. Met dit account kunnen API keys (tokens) worden aangevraagd met toegang tot de demo projecten. omgeving: http://auth.acc.niki.nl inlognaam: contentapidemo wachtwoord: 7V%6?77 Handleiding Niki API 8 / 11
6 Ontwikkelaar modus Vanaf Niki versie 3.28.0 heeft de API een ontwikkelaar modus. De ontwikkelaar modus maakt projecten die nog niet gepubliceerd zijn toegankelijk via de NIKI API. De ontwikkelaar modus verloopt automatisch na 14 dagen. De ontwikkelaar modus moet aangevinkt worden tijdens het aanvragen van een OAuth token en blijft vanaf dat moment 14 dagen geldig. Om de ontwikkelaar modus te verlengen moet het uitgegeven token ingetrokken worden en moet er een nieuw token worden aangevraagd. De ontwikkelaar modus geeft de mogelijkheid een site te bouwen op de API met een project wat wel is ingevoerd, maar nog niet is gepubliceerd. Op deze manier is het mogelijk om een website te bouwen met project gegevens uit Niki zonder het project voortijdig te publiceren. In de ontwikkelaar modus worden concept projecten ook opgenomen in de lijst met projecten. Verder worden concept projecten standaard als koop / huur project doorgegeven. Middels een url parameter 'phase' is aan te geven hoe de API het project moet doorgeven. Zo kan een project 'in voorbereiding' ook als 'koop' of 'huur' worden doorgegeven als alle gegevens zijn ingevoerd. Dit is handig om een nieuwe fase van een project alvast te kunnen testen in een website. 7 Versie parameter In applicatie versie 3.35 zijn nieuwe woningstatussen toegevoegd. Het gaat om de statussen 'tekenafspraak' en 'verkocht onder voorbehoud'. Deze worden standaard niet aangeboden in de API om te zorgen dat bestaande implementaties blijven werken. In plaats daarvan wordt 'tekenafspraak' teruggegeven als 'in optie' en 'verkocht onder voorbehoud' komt terug als 'verkocht'. Om de nieuwe statussen toch uit het systeem te halen kan de parameter 'v=2' worden meegegeven. Op deze manier wordt API versie twee gebruikt en zullen de nieuwe statussen wel worden aangeboden. Handleiding Niki API 9 / 11
8 Omgevingen Niki maakt gebruik van twee omgevingen. Op beide omgevingen is de Niki API beschikbaar. Gebruikers accounts voor de webservice en tokens voor de API moeten voor beide omgevingen afzonderlijk aangemaakt worden en zijn niet uitwisselbaar. Er is geen garantie dat stamgegevens op beide omgevingen overeenkomen. Wij raden aan altijd de API documentatie te gebruiken van de omgeving waarmee gewerkt wordt. Deze documentatie wordt automatisch aangemaakt en komt daarom altijd overeen met de gebruikte omgeving. Het is mogelijk dat er verschillen zijn tussen de omgevingen omdat nieuwe versies altijd eerst op de acceptatie- / testomgeving geplaatst worden. 8.1 Acceptatie en test omgeving De acceptatie- en testomgeving wordt gebruikt voor het testen en accepteren van nieuwe Niki releases. Daarnaast stelt de stichting LNP deze omgeving beschikbaar aan deelnemers en derden voor het testen van aan Niki gekoppelde applicaties. Vanwege het karakter van deze omgeving is hij beschikbaar op basis van best effort. OAuth provider REST API API documentatie 8.2 Live (productie) omgeving http://auth.acc.niki.nl http://api.acc.niki.nl http://api.acc.niki.nl/apidocs De live productie omgeving bestaat uit de www.niki.nl website en diverse gekoppelde sites. Deze omgeving is redundant uitgevoerd en is daardoor permanent beschikbaar. De omgeving bevat actuele gegevens en moet stabiel kunnen opereren. Hierdoor verzoeken wij ontwikkelaars deze omgeving niet te gebruiken voor testdoeleinden. OAuth provider REST API API documentatie https://auth.niki.nl https://api.niki.nl https://api.niki.nl/apidocs Handleiding Niki API 10 / 11
9 Referenties OAuth 1.0 http://tools.ietf.org/html/rfc5849 JSON http://www.json.org/ Handleiding Niki API 11 / 11