API-kontrakten er nyere end modellen

Et kodeeksempel fra hukommelsen kan få en kundeopdatering til at se ubesværet ud. I dette tænkte eksempel skriver en agent et udkast fra hukommelsen. Metodenavnet virker rimeligt. Felterne ser velkendte ud. Testgrundlaget accepterer anmodningen. Men leverandørens rigtige kontrakt blev ændret, efter at eksemplet blev skrevet.

Fejlen begyndte før kaldet. Agenten brugte hukommelse, hvor den havde brug for en aktuel kilde.

Et oplæg om agenter og API’er, der ændrer sig argumenterer for at hente netop den passage, der besvarer opgaven. Princippet er særligt nyttigt ved integrationer, hvor en API-definition er en kontrakt i bevægelse og ikke blot baggrundslæsning.

Et troværdigt kald er ikke en kontrakt

Store modeller lærer fra kode, dokumentation og samtaler skrevet på forskellige tidspunkter. Eksemplerne kan stadig være nyttige for form og skrivemåde. De kan ikke fastslå, hvad en leverandør accepterer i dag, i den version appen bruger, på den konto der er forbundet til synkroniseringen.

Shopifys guide til API-versionering beskriver kvartalsvise udgivelser og versionsspecifikke ændringsnoter. En udvikler kan vælge en understøttet version og derefter læse de ændringer, der vedrører en opgradering. Versionen i anmodningen betyder mere end modellens hukommelse om »Shopify-API’et«.

Brevos reference til oprettelse af kontakter tilføjer et lag: Brugerdefinerede attributter skal findes på kontoen, og værdier, der ikke passer til en attributs definerede type, kan blive ignoreret. Et generisk API-skema kan ikke fortælle agenten, hvilke attributter netop denne konto har oprettet. Det kræver et kontoafgrænset opslag eller en kontrol.

Den aktuelle kontrakt har mindst to dele: leverandørens offentliggjorte handling og kontoens konfigurerede objekter. Agenten har brug for begge, når opgaven afhænger af begge.

Version og kontoafgrænsning bør følge med det hentede svar. En korrekt beskrivelse af en handling i én API-version kan være forkert i en anden. Et korrekt attributnavn på én Brevo-konto findes måske ikke på den næste. Medtag den valgte version og kontoens id i testgrundlaget, og lad testen fejle, hvis en af delene er ukendt. Assistenten bør ikke løse tvivlen ved at gætte ud fra et lignende eksempel.

Hent den lille del, der bruges

En dårlig rettelse er at indsætte ti tusinde handlingsdefinitioner i hver tur med agenten. Modellen får så mere tekst at søge i, flere forældede passager at forveksle og mindre plads til den faktiske opgave. Bed om den handling, der flytter denne post, og de betingelser, der afgør, om den lykkes.

Ved en kontaktopdatering kan det relevante materiale være handlingens sti, tilladte felter, påkrævet id, regler for attributtyper og den aktuelle API-version. Giv agenten de passager sammen med kildeadresserne. Lad resten være tilgængeligt til et andet spørgsmål.

Tajos guide til Brevo-API’et kan hjælpe læseren med at orientere sig hos leverandøren. Den officielle reference bør afgøre et præcist kald, før kode i produktion bruger det. Læseren har brug for en kilde, der kan åbnes igen, når leverandøren ændrer noget.

Et kodearkiv kan gøre det gentageligt. Registrer den fastlåste version, hashværdien af den medfølgende specifikation og datoen for kontrollen. En ændret hashværdi beviser ikke en inkompatibel ændring. Den fortæller den ansvarlige, hvad der skal sammenlignes. En model kan opsummere den relevante forskel. Tests bør stadig afprøve de handlinger, som en fungerende synkronisering afhænger af.

Behandl den genererede anmodning som en hypotese med tre kontroller. Først: Passer den til den officielle handling og den fastlåste version? Dernæst: Indeholder den tilsluttede konto de objekter, anmodningen forudsætter? Til sidst: Efterlader en afgrænset udførelse den forventede tilstand? En skemakontrol kan besvare det første, et kontoopslag det andet og en kontrol med læsning efter opdatering det tredje. Ingen af dem kan erstatte de to andre.

1. Leverandørens handling version · felter

   Hvad det offentliggjorte API accepterer

   afgrænser
2. Tilsluttet konto attribut · type

   Hvad der findes på denne konto

   afgrænser
3. Afgrænset udførelse opdater · læs tilbage

   Hvad der faktisk ændrede sig

Forveksl ikke søgning med bevis for udførelse

Den rimelige indvending er: »Officiel dokumentation kan halte efter den aktive tjeneste.« Det kan den. Det er nødvendigt at læse den, men ikke tilstrækkeligt. En kontrakttest bør sende en afgrænset anmodning gennem samme klientkode og kontrollere både svaret og tilstanden i målsystemet. Hvis tjenesten opfører sig anderledes, så registrer forskellen, og afgræns den berørte handling.

En agent bør også stoppe, når kontrakten er tvetydig. En gættet feltmapping anvendt på mange kontakter er dyrere end én gennemgang af feltdefinitionen. Guiden til at integrere flere virksomhedsværktøjer begynder med at fastlægge den autoritative kilde for hvert dataobjekt. Aktuelle API-oplysninger er samme disciplin anvendt på de handlinger, der flytter objektet.

Prisen er at vedligeholde aktuelle referencer og tests. Alternativet er at betale for den samme forældede antagelse på hver post, synkroniseringen berører.

Modellen kan huske idéen. Den skal læse kontrakten og kontrollere den konto, den er ved at ændre.

Det behøver ikke at gøre hver interaktion langsom. Gem den afgrænsede, versionsbestemte passage og kontoskemaet i cache indtil en kendt hændelse gør dem ugyldige, eller et valgt opdateringstidspunkt nås. Gem kilde og hentetidspunkt sammen med beslutningen. Så betales prisen for et nyt opslag, når kontrakten kan være ændret, ikke for hver gentaget række i en allerede godkendt synkronisering.