Handleiding Niki API - Het Nieuwbouw Platform

Handleiding Niki API
Auteurs:
Datum:
Niki:
Haike Zegwaard (Fundament All Media)
Marcel Mulder (Fundament All Media)
Martin Poelman (Fundament All Media)
24 juni 2016
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
/oauth/requestToken
token autoriseren
/oauth/authorization
token bevestigen
/oauth/accessToken
consumer key
domeinnaam van de website waarop de Niki
API wordt aangesproken
Handleiding Niki API
4 / 11
consumer secret
IMPLEMENT_SECRET
signature method
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-82c47994a008022a
http://api.acc.niki.nl/projects/325/2DVBVDEMO_FOR_SALE?oauth_token=9a96c922d586-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
http://auth.acc.niki.nl
REST API
http://api.acc.niki.nl
API documentatie
http://api.acc.niki.nl/apidocs
8.2 Live (productie) omgeving
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
https://auth.niki.nl
REST API
https://api.niki.nl
API documentatie
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