Base API

Wat is een API

In deze blogpost ga ik niet super technisch in op alle standaarden en onderwerpen die aan bod komen bij een API, maar ik ga globaal uitleggen wat het is en waarom wij daarom een Base API voor al onze applicaties hebben ontworpen. Het staat voor Application Programming Interface en je kunt het goed vergelijken met een stopcontact in je huis. Het stroomnetwerk in je huis is dan je applicatie of website en je voegt een stopcontact toe, zodat iemand een stekker erin kan steken en gebruik kan maken van je stroom. Wat er meestal gebeurd is dat iedereen zijn eigen stopcontact aan het ontwerpen is, de één maakt gebruik van 7 gaten en de andere gewoon 2. Dit komt omdat in de praktijk elke applicatie anders is met andere domein logica. Er zijn echter wel standaarden aanwezig, waardoor het zo makkelijk mogelijk gemaakt kan worden voor de implementerende partij a.k.a. de stekker in dit verhaal.

RESTful API

Dit is de standaard die vaak gebruikt wordt voor een API en staat voor REpresentational State Transfer. Het zorgt ervoor sinds het jaar 2000 dat er een format is waar iedereen zich aan kan conformeren. Wat hierbij belangrijk is dat er goed wordt gekeken naar de standaard. Er zijn nogal wat mensen die zeggen dat ze een RESTful API hebben gemaakt, maar in de praktijk mist er van alles en is het eigenlijk een API met allemaal RPC’s, wat staat voor Remote Procedure Calls (weer zo’n mooie afkorting). Deze RPC’s zijn directe verbindingen met de domain logica van de applicatie, misschien dat het wel in JSON wordt teruggegeven en dat je security goed op orde is, maar dat maakt het niet een RESTful API. Dat is niet goed of fout, maar je moet wel weten waar je mee bezig bent, het zorgt anders voor veel verwarring.

Om toch één voorbeeld te noemen van zo’n standaard, om jullie een idee te geven, wil ik HATEOAS noemen. Weer zo’n mooie afkorting en dit keer staat het voor Hypermedia as the Engine of Application State. Dit zorgt ervoor dat je de API kan zien als een grote bak met allemaal links naar nieuwe content erin. Je geeft alle relevante url’s mee van je API waar op dat moment behoeft aan is voor de eindgebruiker. Wanneer je bijvoorbeeld net https://api.goldenvalue.nl/user/1 hebt opgevraagd dan komen daar links in terug naar bijvoorbeeld https://api.goldenvalue.nl/user/1/location waardoor je weet dat je naar de location url kan gaan. Je API is dus te ontdekken via de links en dat kan eventueel per gebruiker anders zijn, denk aan admins die meer url’s terugkrijgen. Er zijn heel veel redenen waarom je dit zou willen, een goed voorbeeld is paginatie, vorige/volgende links, het heeft voordelen voor je Semantic Versioning en hoe je met changes omgaat in de url-boom van je API. Allemaal voordelen die we graag aan klanten willen aanbieden.

Base API

Aangezien wij heel veel API’s maken voor onze klanten en we vaak aanvragen krijgen voor nieuwe API’s hebben wij een Base API ontwikkeld. Deze Base API maakt gebruik van alle standaarden en komt met de volgende modulaire onderdelen:

• – Security Gateway implementation for multiple security gateways like Oauth2 & SAML
• – Secure setup by checking OWASP
• – Automatic API Documentation generation with Swagger
• – Unit test and Functional testing frameworks
• – HATEOAS implementation
• – SOLID principles used for setup and further development
• – Ready for SOA, DDD, TDD and even Microservice Architecture
• – Available in Docker(recommended), Ansible or Vagrant
• – Ready for Kubernetes and OpenShift with automatic pipeline configs
• – CQRS & Event Sourcing setup included (can be stripped when not needed)
• – Example bundle for explanation of all of the above

Zoals je zit zijn het aardig wat standaarden. Misschien dat we alsnog wat vergeten zijn te implementeren, geef het dan vooral aan tijdens het inventarisatie traject. Naast dat dit een prima basis is voor je API is dit ook een hele goede basis voor je applicatie. Het API-deel hoeft niet meteen beschikbaar te zijn voor je eind gebruikers of derde partijen die gebruik willen maken van je applicatie. De applicatie is er dan al wel helemaal klaar voor en daarnaast opgebouwd volgens de juiste SOLID principles en opgezet in schaalbare componenten voor Kubernetes.

Voordelen

Het hebben van zo’n Base API geeft ons en de klant veel voordelen: Het zorgt voor een snellere livegang van de applicatie wanneer de Base API wordt aangeschaft, je koopt een hoop tijd terug voor een goede basis van je applicatie. Developers kunnen er goed op door ontwikkelen omdat alle standaarden worden toegepast. Het is makkelijk om nieuwe developers in te werken in de applicatie vanwege alle voorbeelden en standaarden. De onderhoudbaarheid van de applicatie is hoog aangezien het motiveert om Unit tests en Functionele tests toe te voegen en vanwege alle principes die gehanteerd worden. Kortom, zoals ik vaak zeg: Niet doen is duurder. En waarschijnlijk heb ik nog gelijk ook vanwege de winst op je ROI, Time to Market, eventuele mindering op hosting kosten in Kubernetes (Lees hier meer over onze hosting oplossing https://scalia.nl) en de mindering van onderhoudskosten na een paar jaar.

Mocht je dit lezen en denken: dat is superhandig! Of: kunnen wij dit ook niet goed gebruiken? Neem dan vooral contact op met onze Sales Manager Sebastiaan Alberts voor een vrijblijvende afspraak. Hij zal eventueel met een software architect samen uitleg geven over onze manier van werken en een kostenindicatie kunnen afgeven. Bedankt voor het lezen!