REST API Richtlijnen

Betrouwbaarheid

  • Aangeboden berichten worden bevestigd d.m.v. een "201 Created" melding. Pas als deze melding door het bronsysteem is ontvangen mag worden aangenomen dat Flowmailer het bericht zal verwerken.
  • Er kan altijd iets mis gaan, waardoor het noodzakelijk is om een mechanisme te hebben om berichten opnieuw aan te kunnen bieden zonder deze te verliezen. Het is daarnaast aan te raden zo'n 'retry mechanisme' te voorzien van een vorm van een wachtrij (queue) op disk om landurige problemen op te kunnen vangen.
  • De Flowmailer REST API wordt aangeboden op meerdere IP adressen. In geval van meerdere pogingen verdient het aanbeveling daarvoor ook verschillende IP adressen te gebruiken.

Veiligheid

  • Maak altijd gebruik van HTTPs verbindingen, waarbij de geldigheid van het door de Flowmailer API aangeboden certificaat wordt gevalideerd.
  • Gebruik voor verschillende bronsystemen en OTAP-varianten daarvan verschillende API credentials. Voorzie deze ook van de minimaal vereiste rol; om alleen berichten te verzenden zijn bijvoorbeeld geen Admin rechten nodig.

Onderhoudbaarheid

  • Accepteer elk geldig certificaat waarvan een vertrouwde keten kan worden gevalideerd. Registreer dus niet het specifieke certificaat dat op dit moment wordt gebruikt, om onnodige problemen voor te zijn wanneer verloopt en deze vervangen moet worden.
  • In principe veranderen de door Flowmailer gebruikte IP adressen zeer zelden, maar maak in ieder geval gebruik van de DNS namen waar mogelijk (dus niet direct IP adressen) en richt de omgeving zodanig in dat eventuele wijzigingen snel worden opgepakt.

Performance

  • Het na authenticatie verkregen token is geldig voor meerdere aanroepen. Gebruik deze dus, zeker wanneer er sprake is van een batch proces, zolang deze geldig is.
  • Maak gebruik van HTTP keepalive, waardoor meerdere aanroepen over dezelfde verbinding kunnen worden gemaakt. Het tot stand brengen van nieuwe HTTPs verbindingen is een relatief langzaam proces, wat bij herhaalde aanroepen tot aanzienlijke vertraging kan leiden.

Fair use

  • Voorkom onnodige belasting, bijvoorbeeld door rapportages herhalend met overlappend datumbereik op te vragen. Dit leidt tot onnodige belasting, vertraagt het proces en biedt geen meerwaarde.
  • Richt de processen zodanig in dat de combinatie van gebruikte API aanroepen een efficient geheel vormt in de gegeven situatie. Als het bijvoorbeeld wenselijk is om alle nieuwe events rond berichten te ontvangen is het niet efficient om herhaaldelijk om de status van alle individuele berichten te vragen, maar om gebruik te maken van de message_events aanroep.