Technologie

RESTful webservice

Moderne applicaties bieden koppel mogelijkheden zodat ze onderling met elkaar kunnen communiceren. In dit artikel gaan we in op Moneybird en welke technieken door ons gebruikt zijn om met deze applicatie te koppelen. De Moneybird koppeling wordt gebruikt om uren die wij importeren vanuit UurOnline en Nocore te Factureren in Moneybird. Meer over de case zelf kunt u bekijken via onderstaande link.

De case >

Wat is Moneybird

Boekhoud paketten zijn een klein onderdeel van een bedrijf. Naast een boekhoudpakket worden er in een bedrijf vaak ook andere software applicaties gebruikt voor de bedrijfsvoering, bijvoorbeeld Nocore voor het verlonen van uren.

Omdat Moneybird zichzelf ook ziet als een kleine schakel in de keten hebben ze een uitgebreide API. Dit betekend dat andere applicatie met Moneybird kunnen communiceren. Op deze manier kan Moneybird geïntegreerd worden in een bestaand bedrijfsproces.

Door te koppelen op applicatieniveau kan het hele proces van verloning tot facturatie geautomatiseerd worden.

Authenticatie met OAuth

Omdat een applicatie met de Moneybird API koppelt moet deze eerst geauthenticeerd worden. De applicatie zelf wordt geregistreerd bij Moneybird waarna Monebyird een zogenoemde Client ID en Client Secret uitgeeft.

Met deze gegevens kan een access_token opgevraagd worden. Deze token is een bepaalde tijd geldig en wordt meegestuurd bij het opvragen van gegevens. Vaak als Bearer token. Deze manier van koppelen wordt OAuth 2 genoemd. OAuth 2 is een standaard voor autorisatie waarbij gebruikers een programma toegang geven tot hun gegevens zonder hun gebruikersnaam en wachtwoord uit handen te geven. curl -XGET -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" https://moneybird.com/api/v2/107693607045039116/contacts.json

REST Architectuur

De techniek die Moneybird heeft gekozen voor zijn Api is REST (Representational state transfer). Dit is een software architectuur die voorschrijft hoe een API er uit moet zien. API's die deze architectuur implementeren worden ook wel RESTful genoemd. Deze architectuur is initieel bedacht door Roy Fielding

Een entiteit waarvan gegevens binnen gehaald moeten worden kan benaderd worden via een duidelijk pad. Manupulatie van de entiteit gebeurt via de bekende HTTP acties (GET, POST, PATCH, PUT, DELETE). Dit maakt de API voorspelbaar en duidelijk. Een alternatief voor REST is bijvoorbeeld SOAP ( Simple Object Access Protocol).

Ruby on Rails is een goed voorbeeld van een framework waarbij REST in alle facetten is doorgevoerd.

https://moneybird.com/api/:version/:administration_id/:resource_path.:format

Webhooks

Bij het koppelen met een andere applicatie zijn er twee mogelijkheden. De makkelijkste en minst efficiënte is dat je periodiek de andere applicatie vraagt of er nog nieuwe gegevens zijn (polling).

Een betere manier is het gebruik maken van webhooks. Met deze techniek wordt de applicatie automatisch een bericht gestuurd als er bijvoorbeeld een contact in Moneybird wordt aangemaakt.

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84qc207ad0154a508f7s198e615a998ac1fd712926d00f945fb1df2e044cba44zb" \ -XPOST \ -d '{"url":"http://www.mocky.io/v2/5185415ba171ea3a00704eed","events":["contact_created"]}' \ https://moneybird.com/api/v2/123/webhooks.json

ASP.NET Core

Moneybird zelf is geschreven in Ruby on Rails en omdat de community by Ruby on Rails zo groot en actief is, is er een uitstekende 'Gem' om te verbinden met Moneybird. De klant maakt echter gebruik van C# en .NET. Omdat de Moneybird API goed is gedocumenteerd en er ook met andere applicaties gekoppeld moet worden is er gekozen voor een ASP.NET Core applicatie gehost op een CentOs machine. Door het gebruik van ASP.NET Core in plaats van ASP.NET 4.x kon er gekozen worden voor een CentOs Virtual Private Server hosting oplossing. Daarnaast biedt ASP.NET Core diverse andere voordelen ten opzichte van ASP.NET 4.x. Het feit dat de klant ook kennis heeft van .NET en C# zorgt ervoor dat de code makkelijk over te dragen is.

Daarnaast is er gekozen voor C# Razor pages en een simpel achtergrond proces dat synchronizeert met Moneybird. De Razor pages zijn gebruikt omdat er een kleine front end applicatie nodig was waarin een administrator aanpassingen kan doen in het facturatie proces. Razor pages biedt in dit geval een alternatief voor het implementeren van een complete MVC applicatie.

Lees verder over de case waar wij een koppeling realiseren tussen Nocore, UurOnline en Moneybird.