De API Developer Experience – 3 mythen, 3 suggesties, 3 feiten

We begeven ons in de richting van een wereld waarin we onze apparaten steeds beter leren kennen. We praten tegen ze en zij praten tegen ons; kortom, we wisselen informatie uit. Nooit eerder voelden we ons zo verbonden met onze apparaten en nooit eerder voelden ze zo persoonlijk. Van gezondheidsmonitoringssystemen tot drones en van thermostaten tot smartphones; we plukken de vruchten van alles wat ze aan onze levens toevoegen.

Flavia Sequeira-van Harten

Er zullen steeds meer apparaten aan ons leven worden toegevoegd, allemaal met het streven om de kwaliteit van ons leven te verbeteren. Hoewel dit technologisch gezien en vanuit een consumentenoogpunt geweldig is, stelt het ons, de IT’ers, voor een grote uitdaging. Aan de ene kant hebben we een ingewikkeld IT-systeemlandschap en aan de andere kant de talloze apparaten die aangestuurd moeten worden. Hoe gaan we om met deze complexiteit? API’s kunnen het gat tussen IT-systemen en devices overbruggen.

Laten we de zogenoemde API Value Chain eens bekijken. Een API geeft een bedrijfsonderdeel weer. Deze API wordt door één of meerdere apps geconsumeerd. En déze apps zijn de manier waarop de uiteindelijke consument jouw diensten ervaart.

Afbeelding 1 – API Value Chain

Het moge duidelijk zijn dat deze apps zeer belangrijk zijn, niet alleen in het leveren van een goed product aan de uiteindelijke gebruiker, maar ook voor het succes van jouw API. En toch wordt de ontwikkelaar die deze prachtige apps maakt vaak vergeten als het aankomt op het bouwen van API’s.

Ik wil graag drie gangbare mythen onder de aandacht brengen, waar teams die API’s bouwen mee te maken hebben:

Mythe 1: We denken later wel na over de developers-ervaring. Het is toch voor publieke API’s?
Mythe 2: Ontwikkelaars zullen onze API geweldig vinden. Hij is immers perfect, toch?
Mythe 3: Wij weten wat het beste is voor onze API. Ontwikkelaars hoeven ons echt niet de les te lezen.

Met zo’n houding kom je niet ver. Aangezien er meer dan 12.000 publieke API’s zijn (op het Programmable Web^[1]) om uit te kiezen, zal jouw API hetzelfde zijn als een geweldige film die niemand iets kan schelen. Het doel van dit artikel is het geven van nieuwe inzichten die je zullen helpen API’s te bouwen waar ontwikkelaars dol op zijn.

Suggestie 1: Behandel jouw API als een product

Een API is meer dan alleen een software interface. Het is een interface naar jouw bedrijfsinstelling, jouw diensten en jouw organisatie. Het zou geen moeite moeten kosten om er gebruik van te maken en prachtige apps mee te creëren. Behandel hem daarom als een product en stel alles in het werk om van dat product een succes te maken.

Bijvoorbeeld:

Geef je API een URL; zorg dat hij gevonden kan worden. Is het een publieke API, registreer hem dan bij http://apis.io/
Zorg voor eenduidige gebruiksvoorwaarden. Laat het opstellen hiervan niet over aan de juridische afdeling. Dit is jouw product. Stel de voorwaarden zelf op.
Zorg dat het registratieproces toegankelijk is. Niets zo vervelend als honderd keer te moeten klikken om toegang te krijgen tot een API.
Documenteer je API grondig. Hoewel documentatie onderschat wordt, wordt deze gelezen door iedereen die jouw product wil gebruiken. Zorg ervoor dat de documentatie actueel is.
Software Development Kits (SDK’s) zijn fantastisch om mensen met je API te laten ontwikkelen. Zorg ervoor dat ontwikkelaars met jouw API makkelijk app’s kunnen schrijven. Stel Hello World-voorbeeldapps ter beschikking.
Kondig releases aan en zorg voor release notes.
Zorg voor sandboxes waarin ontwikkelaars je API kunnen testen en ermee kunnen spelen.
Neem feedback serieus en zorg voor ondersteuning.

Suggestie 2: zorg voor gebruiksgemak

Een API die niet makkelijk te gebruiken is, zal hoogstwaarschijnlijk niet worden gebruikt. Zorg ervoor dat je hem intuïtief houdt voor een app-developer. Houd er rekening mee dat die developer niet altijd inzicht heeft in jouw bedrijf.

Bijvoorbeeld:

REST^[2] is het best; creëer geen eigen conventies.
Gebruik alleen JSON^[3] voor dataweergave. JSON is verreweg de populairste weergave voor cliënten op basis van JavaScript.
Maak gebruik van HTTP voor alles (statuscodes, methodes, enzovoorts). Ga geen eigen standaarden ontwikkelen.
Maak gebruik van hypermedia om de navigeerbaarheid van jouw API te verbeteren. Als de data de state is, is hypermedia de state transfer. Beide aspecten zijn even belangrijk voor een buitengewone API.
Maak gebruik van OAuth 2.0-authenticatie^[4].
Stel curl^[5] Scripts beschikbaar om toegang tot je API te krijgen en om deze te kunnen uitproberen.
Denk na over de verschillende type cliënten die gebruik zouden kunnen maken van jouw API, zoals bijvoorbeeld mobiele cliënten en schermloze clië
Werp geen hindernissen op voor bestaande clië Implementeer geen onoverkomelijke wijzigingen.
Een geweldige API weet wie zijn publiek is. Toon geen intern jargon.

Suggestie 3: Sta open voor innovatie

Het maken van een API voor een specifieke cliënt en voor een specifieke behoefte kan een goed beginpunt zijn, maar het is zeker niet de eindbestemming. Denk groot! Een buitengewone API heeft enorm veel potentie. Om deze potentie aan te boren, moet je open staan voor innovatie. Deze innovatie zal zeer waarschijnlijk komen van de gebruikers van jouw API.

Bijvoorbeeld:

Developers zijn niet achterlijk. Leer ze kennen.
Nodig hen uit feedback te geven. Gebruik dit als aansporing om jouw API te verbeteren.
Organiseer hackathons met gebruikers. Gezamenlijk zullen er bijzondere dingen ontstaan.

Ik hoop van harte dat je deze suggesties zult overwegen bij het bouwen van jouw volgende API. Ik wil dit artikel graag afronden met de drie feiten die eraan herinneren dat een API méér is dan alleen een software interface.

Feit 1: de waarde van een API hangt helemaal af van de waarde van de apps die ermee worden ontwikkeld.
Feit 2: hierdoor is de API Developer Experience van wezenlijk belang.
Feit 3: Net als alle goede ervaringen moet de API Developer Experience ontworpen worden.

Een groot man heeft ooit gezegd: ‘Maak niet alleen een ontwerp van hoe het eruitziet. Maak een ontwerp van de werking.’ Met andere woorden: Maak een ontwerp dat ertoe doet! Maak een ontwerp dat ertoe doet! Maak een ontwerp dat ertoe doet!

^[1] Programmable Web API Directory (http://www.programmableweb.com/apis/directory)

^[2] REST architectural style (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

^[3] JSON (http://json.org/)

^[4] OAuth 2.0 (http://oauth.net/2/)

^[5] Curl (http://curl.haxx.se/)