Werken met de SuiteCRM-Webservices

Ben je een ontwikkelaar, of wil je meer weten over hoe SuiteCRM kan communiceren met andere applicaties? Hebt je de beschikking over SuiteCRM en ga je nu werken met de API omdat je andere applicaties gegevens wilt laten uitwisselen met het CRM? Dan is deze blog interessant voor jou. We vertellen over de API’s die in SuiteCRM aanwezig zijn en geven je handvatten om de eerste stappen te zetten.

Welke API’s zijn er beschikbaar?

1. Momenteel zijn er twee mogelijkheden;

• De oude API, genaamd “v4.1”
• De nieuwe API, genaamd “V8”

Wij raden aan om alleen te werken met de nieuwe V8-API omdat de oude versie wordt uitgefaseerd en daarom nu ook niet verder onderhouden.

Het vinden van informatie over de V8 API

Juiste documentatie

Het is verstandig bij het ontwikkelen eerst goed te kijken in de documentatie en actief in de gaten te houden welke ontwikkelingen er spelen. Als je juist meer achtergrond informatie wilt hebben over de oude code ga dan via De developer docs van SuiteCRM naar Hst 2 Developer Guide – API Versions. Kijk voor de nieuwe API bij Hst API Versions / API V8 voor belangrijke gerelateerde informatie. Bekijk wanneer van toepassing ook andere Hoofdstukken zoals Hst. Best Practices, Further Resources, Appendix C – Automated Testing, JSON API en JSON API Error Object.

Ga voor de laatste informatie naar “docs.suitecrm.com” en bekijk op deze homepage bijvoorbeeld bij “RECENTLY EDITED” voor specifieke recente zaken, zodat je altijd op de hoogte blijft.

Codevoorbeelden en frameworks

Het kan zijn dat je bezig bent met het ontwikkelen van code die gebruik maakt van deze Rest API’s en je wilt graag kijken naar complete voorbeelden. Waar moet je dan gaan zoeken? Je kan dat doen op verschillende plaatsen. Kijk voor echte voorbeelden op GitHub bij; mattkol-Java, mattkol – .Net, ste80pa, ProcessFast en shijinkrishna.

Als je nog bezig bent met de oude Api v4.1 versie ga naar Handleidingen SugarCRM 6.5 oud en download daar de juiste documentatie zoals de Developer Guide. Zoals reeds genoemd, raden wij aan deze API niet meer te gebruiken (en dan m.n. voor nieuwe projecten).

Actieve ontwikkerlaars op het SuiteCRM forum

Sommige van deze ontwikkelaars zijn ook actief bezig op het forum van SuiteCRM. Kijk ook op dit forum om daar voorbeelden te vinden en andere informatie op te zoeken. Ga naar https://community.suitecrm.com/search en maak gebruik van “de Advanced Search”. Zoekterm “API v8” geeft al veel specifieke resultaten terug. Mogelijk dat jouw situatie daar tussen zit of anders kan je daar ook een vraag plaatsen. Houd rekening mee dat het een Community forum is en daarom je niet meteen een antwoord krijgt.

Problemen oplossen

Error handling / foutafhandeling

Hierboven hebben we de zaken behandeld waarmee je rekening moet houden en waar je snel de juiste informatie kan vinden als je bezig bent met het ontwikkelen. Maar, zoals in elk project, kan je altijd te maken krigjen met fouten en die moet je afhandelen. Wat heb je nodig om deze foutafhandeling te organiseren en om de juiste informatie weer te geven?
Kijk daarvoor op de Dev Guide – JSON API Error Object. SuiteCRM geeft zelf een beknopt voorbeeld.
Als je dit voorbeeld wilt uitbreiden, ga dan naar JSON:API – Errors . Op die pagina zie je welke informatie je terugkrijgt bij fouten en die je kunt gebruiken om die op te lossen en nuttige berichten weer te geven.

Welke informatie is er verder beschikbaar?

Zoals je in de documentatie kunt lezen, is de foutresponse al behoorlijk communicatief. Het is belangrijk dat je een doordachte strategie hebt en dat je uit het bericht goed kan opmaken of de situatie afhankelijke is van de client of de server kant. Door jouw reporting hierop af te stemmen kan je sneller achterhalen hoe jouw situatie is veroorzaakt, waar jij moet zoeken en wat de oplossing is. Bij een client melding moet je in jouw eigen code kijken en bij server kant kan je vragen stellen bij de beheerder van jouw app instance. Dus eerst moet je weten wat te doen bij een succesvolle API Call en bij een mislukte API Call.

In beide gevallen moet je kijken wat te doen nadat je een Call hebt gedaan. Bij een succesvolle Call kan je doorgaan met de volgende stappen, maar bij een mislukte Call is het goed om te bedenken wat je eerst terug moet krijgen. Een goede error reporting is precies en laat de aard zien van de error waardoor men hier mee weet om te gaan en deze informatie kan gebruikt om jouw situatie op te lossen.

Hoeveel http-statuscodes zou je moeten gebruiken bij het werken met jouw Rest constructie? Als je het concreet maakt komt het op neer dat er maar 3 verschillende uitkomsten zijn tussen de applicatie en API.

1. Actie is succesvol – 200 http response
2. De fout ligt bij de applicatie – 4xx http response
3. De fout ligt bij de API (serverkant) – 5xx http response

Wanneer je werkt met melding “200 – OK”, denk er dan aan dat je op de juiste manier werkt met deze “HTTP response status code” zoals dat intern is vastgelegd.
Een melding “400 – Bad request” moet je gebruiken om een niet specifieke mislukte Call weer te geven. “400 – Bad request” is een generieke client kant status en een goed alternatief wanneer er geen specifieke 4xx is gebruikt. Wanneer je wel werkt met 4xx type status codes, dan moet de status melding een verwijzing bevatten naar de documentatie waarin de juiste client error wordt beschreven en daarbij ook de oplossing.
Een 500 – Internal Server Error gebruik je als een algemene mislukte API Call. Een 500 Status code komt nooit door een client, maar altijd door de server. Die fout aan de serverkant kan natuurlijk wel komen doordat de client onverwachte of incomplete gegevens aanlevert.

Eerder hadden we het al over de 4xx type status codes. De lijst met client kant status codes zou je kunnen uitbreiden met minimaal drie extra specifieke meldingen. Denk aan de onderstaande drie;

1. 401 – Unauthorized
2. 403 – Forbidden
3. 404 – Not Found

Een 401 melding gebruik je wanneer er problemen zijn met de inloggegevens van een gebruiker. Dat kan zijn wanneer deze toegang wil krijgen tot een bron zonder het verschaffen van de juiste autorisatie. Wanneer dat niet goed gaat kan je zo’n melding krijgen. Een andere belangrijke is status code 403 – Forbidden, gebruik deze wanneer de gebruiker geen toegang mag krijgen tot een bron, zelfs wanneer deze wel over de juiste autorisatie beschikt. Door deze 403 melding handhaaf je de permissie niveaus. Een handige andere Status code melding is 404 – Not Found. Deze melding geeft aan dat de gebruiker een typefout heeft gemaakt in de URL of dat de pagina niet meer bestaat.

Samengevat

Waarschijnlijk is het de beste manier om te werken met Rest API-web services door een compacte error reporting op te zetten. Gebruik minimaal de volgende, maar ga niet verder dan 10 type meldingen.

1. Handige Status codes:

• 200 – OK
• 400 – Bad Request
• 401 – Unauthorized
• 403 – Forbidden
• 404 – Not Found
• 500 – Internal Server Error

De keuze welke error berichten te gebruiken hangt ook af van hoeveel verschillende uitkomsten er mogelijk zijn. In sommige gevallen zijn er maar drie uitkomsten;

1. Alles werkt
2. De app heeft iets fout gedaan
3. De APi heeft de Call niet juist afgehandeld

Verder moet jouw error reporting voldoende informatie bevatten om de situatie op te lossen. Er moet een goede uitleg in jouw bericht staan die de situatie uitlegt en een oplossing wat te doen met het error bericht als men deze terugkrijgt na een API Call.