Jared Cheney / 7 september 2017
Noot van de redactie: we publiceren af en toe gastposts op de Zapier Engineering Blog, zoals deze van Jared Cheney, een senior software-ingenieur bijT-bladen.
Ik ben van mening dat je, om een geweldig product te bouwen, je eigen hondenvoer moet eten – of, met andere woorden, dat je alle functies en documentatie van je product moet gebruiken voordat je het aan je klanten vrijgeeft. Je krijgt een voorproefje van alles wat je bouwt.
Ik heb dit op de harde manier geleerd.
Trek een kom omhoog, het is chow-tijd
Toen we in 2008 de eerste iteratie van onze API produceerden, dachten we dat we goed werk hadden geleverd door deze te ontwerpen voor alle vereiste gebruiksscenario's. We dachten dat het koeler was dan de teennagels van een ijsbeer, en we verwachtten dat de integraties zouden binnenrollen.
Omdat we graag de vruchten van ons werk wilden plukken, hebben we de ontwikkeling van een desktopwidget uitbesteed aan een externe ontwikkelaar. Ze hebben er een tijdje aan gewerkt en we hebben allerlei vragen beantwoord over hoe we onze API konden gebruiken om aan de eisen te voldoen die we hen hadden gesteld. Op hun verzoek hebben we zelfs enkele wijzigingen doorgevoerd. Maar toen het er uiteindelijk op aankwam om te gebruiken wat ze hadden ontwikkeld, werkte het niet zoals wij dat wilden.
Er waren problemen met de manier waarop de status van een ingeklokte gebruiker werd beheerd, vooral wanneer die gebruiker schakelde tussen meerdere methoden om zijn tijd gedurende de dag bij te houden. Terwijl we ons verdiepten in de details van hoe we het zouden kunnen ‘repareren’, realiseerden we ons dat het ontwerp en de architectuur van onze API hen op het pad hadden gedwongen dat ze waren ingeslagen.
Uiteindelijk kwamen we tot de conclusie dat onze API zoals die op dat moment was, niet zou werken voor het project zoals we ons hadden voorgesteld, en uiteindelijk hebben we de desktopwidget helemaal geschrapt. Als we de dingen anders hadden gedaan met onze API, zou het veel tijd en geld hebben bespaard, en hadden we een bruikbaar product van onze externe ontwikkelaar gekregen.
Vanaf dat moment hebben we een aantal regels opgesteld:
- We zouden altijd de eerste consument van onze API zijn.
- We zouden onszelf dwingen om onze API voor zoveel mogelijk bewerkingen te gebruiken, zodat we de lessen snel konden implementeren en aanpassingen konden doorvoeren terwijl we bouwden.
- We zouden alle nieuwe toevoegingen aan onze API ontwikkelen en documenteren, samen met de functies waarvoor deze nodig waren.
Dogfooding Onze Android-app
Op dit punt hadden we verschillende verbeteringen aan onze API aangebracht en de klus werd geklaard. Maar we stonden te popelen om een herkansing te krijgen. We wilden enkele belangrijke architecturale beslissingen wijzigen die we hadden genomen met betrekking tot authenticatie en onze verzoek/antwoordstroom.
Snel vooruit naar 2012 en we begonnen een nieuw project om een native te schrijvenTSheets Android-applicatie. Nu hadden we de kans om onze API te herschrijven en te kijken of de regels die we onszelf hadden opgelegd de voordelen zouden opleveren die we voor ogen hadden. We zijn begonnen met het vaste doel om volledig op onze API te vertrouwen zodat onze Android-app met onze service kan werken, en om alles te ontwikkelen met de bedoeling dat het openbaar beschikbaar zou worden gemaakt.
Terwijl we de nieuwe API ontwikkelden, plaatsten we onszelf in de schoenen van een externe ontwikkelaar en vroegen we ons voortdurend af: “Hoe zou ik willen dat de API zich zou gedragen?” We bouwden één onderdeel van onze app tegelijk uit en terwijl we leerden over elk onderdeel dat we nodig hadden, ontwikkelden we het bijbehorende API-eindpunt om tegelijkertijd aan die behoefte te voldoen. Als we merkten dat we de output niet efficiënt konden consumeren of dat we informatie misten die we nodig hadden, zouden we dingen aanpassen totdat het precies aan onze behoeften voldeed.
Wat goed is voor de klant, is goed voor jou
Een vroege uitdaging die we moesten aanpakken, deed zich voor toen we probeerden onze applicatie offline te laten werken, waardoor we bij de eerste synchronisatie veel gegevens voor onze grotere klanten moesten ophalen.
We haalden bijvoorbeeld de urenstaten van de afgelopen vier weken voor de gebruiker op en elke urenstaat kon naar meerdere velden verwijzen, dus we moesten de velddefinities en de mogelijke waarden voor die velden downloaden en welk veld daadwerkelijk was gekozen. voor elke urenstaat.
Omdat onze API traditionele REST-patronen volgde, merkten we dat we meerdere oproepen deden om alles op te halen wat we nodig hadden, alleen maar om historische gegevens weer te geven, laat staan alles wat nodig was om de gebruiker meteen te laten inklokken! Het eerste synchronisatieproces duurde gewoon te lang. We waren gefrustreerd door het wachten en vreesden dat onze klanten nog minder vergevingsgezind zouden zijn.
Onze oplossing voor dit probleem werd iets dat we in elk antwoord van onze API onder de sleutel opnemenaanvullende_gegevens. We hebben besloten dat we naast de aangevraagde primaire objecten ook een exemplaar zouden opnemen van elk object waarnaar wordt verwezen door een van de primaire objecten in de database.aanvullende_gegevensdeel van de reactie.
Ook al vereiste het meer overhead op de servers die de respons genereerden, het was prachtig voor de consument van de API. Nu konden we twintig urenstaten ophalen en beschikken over alle benodigde informatie om die urenstaten te ‘hydrateren’ met de informatie die deze bruikbaar zou maken voor onze eindgebruiker. En we konden dit bereiken met één enkel API-verzoek.
Laat de vereisten van de app de eindpunten bepalen
Omdat we tijdens dit hele proces aan beide kanten van de ontwikkelaar/API-relatie stonden, verliep de voortgang extreem snel. En we hadden aan beide kanten voorstanders die vertegenwoordigden wat belangrijk was, dus er moesten compromissen en herinrichting plaatsvinden totdat beide partijen tevreden waren.
Er kwamen verschillende patronen naar voren over hoe we onze antwoorden zouden formatteren en wat ze zouden bevatten, en we konden deze patronen toepassen op elk eindpunt dat we ontwikkelden. Terwijl we de app bleven ontwikkelen, lieten we de vereisten van de app bepalen aan welke eindpunten we vervolgens werkten.
Uit onze ervaring met een eerste, tweede en derde iteratie van onze API die momenteel in uitvoering is, hebben we een paar dingen geleerd:
1. Houd u aan de YAGNI-regel.
"You Are't Gonna Need It" heet de afkorting YAGNI, zoalsbeschreven door Martin Fowler. Bouw dingen niet te ver uit, anders kijk je misschien terug op een hoop verspilde tijd en moeite als je beseft dat je het nooit gebruikt of dat het moet worden gewijzigd om bruikbaar te zijn.
2. Vermijd ‘verborgen’ of ‘speciale’ API-eindpunten die alleen jij kent.
Als je iets verborgen houdt voor externe ontwikkelaars en voor jezelf reserveert, bescherm je jezelf tegen de pijn die zij zouden kunnen voelen. U wilt uzelf in hun positie verplaatsen, zodat uw sympathie groeit en u motiveert om uw API zo goed mogelijk aan uw behoeften te laten voldoen. Dit komt uiteraard ten goede aan alle externe ontwikkelaars die met u in hetzelfde schuitje zitten.
Anders kunt u te veel gaan vertrouwen op enkele verborgen functies van uw API om aan uw behoeften te voldoen. En als jij die behoeften hebt, is de kans groot dat anderen die met jou willen integreren dat ook zullen doen.
Als u absoluut over een API-mogelijkheid moet beschikken die beperkt is tot uw eigen applicaties, moet u deze nog steeds documenteren en ontwerpen met het idee dat een externe ontwikkelaar ze op een gegeven moment kan gebruiken. Anders is de natuurlijke neiging om het “net goed genoeg” te krijgen voor eigen gebruik, en ontstaan er technische schulden die moeten worden afgehandeld wanneer u deze functies eindelijk voor externe ontwikkelaars inschakelt.
3. Maak onderweg een lijst met tips en trucs.
En bouw ze in uw documentatie! Ze moeten bestaan uit de logica die u hebt gebruikt om stromen tot stand te brengen die gebruikelijk zijn bij het gebruik van uw API. We hebben bijvoorbeeld een aanbevolen manier om de toegewezen functiecodes voor een gebruiker op te halen, zodat u zowel de toewijzingen als de gerelateerde functiecodeobjecten in hetzelfde antwoord krijgt (met behulp van deaanvullende_gegevenshierboven genoemd).
We laten u ook zien hoe u het beste snel kunt bepalen welke objecten zijn gewijzigd sinds de laatste keer dat u onze API hebt opgevraagd. Door dit soort ‘recepten’ aan uw consumenten te geven, kunt u hen moeite besparen en ervoor zorgen dat de interactie met uw API efficiënt is.
4. Het eindresultaat is een stuk beter dan hondenvoer.
Als u gedisciplineerd kunt zijn in het ontwikkelen en documenteren van nieuwe toevoegingen aan uw API in combinatie met de functies die deze vereisen, krijgt u een API die volledig is uitgerust, goed gedocumenteerd en gemakkelijk te gebruiken is.
De ontwerper moet de handleiding schrijven
Hoe graag ik er ook aanspraak op zou willen maken, ‘dogfooding’ is geen nieuw concept. In 1989 publiceerde Donald Knuth een artikel waarin hij de lessen vertelde die hij leerde uit de ontwikkeling van zijn TeX Typesetting-software, waarin hij de voordelen noemt die voortkomen uit het gebruik van een ‘dogfooding’-aanpak:
“Zo kwam ik tot de conclusie dat de ontwerper van een nieuw systeem niet alleen de uitvoerder en de eerste grootschalige gebruiker moet zijn; de ontwerper moet ook de eerste gebruikershandleiding schrijven. De scheiding van een van deze vier componenten zou TeX aanzienlijk hebben geschaad. Als ik niet volledig aan al deze activiteiten had deelgenomen, zouden er letterlijk honderden verbeteringen nooit zijn aangebracht, omdat ik er nooit aan had gedacht of zou hebben begrepen waarom ze belangrijk waren.”
— Donald E. Knuth,De fouten van TeX, Software-Praktijk en ervaring, VOL. 19(7), JULI 1989, blz. 622
Amen, broeder.
Want zoals ze in de reclame van Kibbles 'n Bits zeggen: "De ideale maaltijd voor uw hond is niet wat hij eet, maar wat u eet." Mij? Ik geef de voorkeur aan de kipsmaak.