Gå til hovedinnhold
Mål

Når du er ferdig med dette punktet, har du:

  • Valgt en samarbeidsform som passer teamet
  • Valgt et verktøy for dokumentasjon av designvalgene som passer teamets sammensetning, kompetanse og foretrukne arbeidsformer

Velge arbeidsverktøy og samarbeidsformer

Vi har ingen retningslinjer for hvordan man gjør API-design, og oppfordrer hvert team til å finne en måte å jobbe på som gir fart og flyt til arbeidet. Likevel har vi noen råd basert på erfaringene vi har gjort oss så langt.

Samarbeidsform​

API-design er en tverrfaglig oppgave, som normalt krever samarbeid. Det finnes flere måter å organisere samarbeidet på. Vi har erfaring med følgende samarbeidsformer:

Designworkshop​

Vi har gode erfaringer med å gjøre API-design både for GraphQL og REST i workshopformat, med all relevant kunnskap og kompetanse i samme rom. Dette egner seg kanskje særlig for team som akkurat har begynt med API-design, eller der designet krever mye utforskning. Dette formatet gir gode forutsetninger for å utnytte hele teamets kompetanse og få inn forskjellige perspektiver. Det gir også trygghet og forankring for valgene som gjøres.

Erfaringene til nå tilsier at workshopen blir mest effektiv dersom den som leder den, har utarbeidet et forslag til design på forhånd.

Code review​

Utviklere er allerede godt kjent med code review-prosessen, og en slik prosess egner seg også godt til å samarbeide om API-design.

Erfaringen til nå er at det også er enkelt å onboarde ikke-utviklere på verktøyene som kreves for å delta aktivt i prosessen, og at det gir god fart til arbeidet i en fase hvor det ikke skal tas mange prinisippelle valg. Dersom det er vanskelig å samle alle relevante personer på samme tidspunkt, eller dersom arbeidet krever samarbeid på tvers av team, er dette et godt alternativ til workshop.

Arbeidsverktøy​

API-designet skal resultere i en spesifikasjon som brukes til å generere eller implementere et API. Spesifikasjonen må angi hvordan APIet skal se ut, og hvordan det skal mappes til kolonner og tabeller i FS. Hvilket verktøy som egner seg best til å beskrive dette, avhenger av hvilken samarbeidsform teamet velger, og hvem som fører spesifikasjonen i pennen. Her er det erfaringsmessig også litt forskjell på REST/OpenAPI og GraphQL.

Vi har erfaring med følgende verktøy:

Skrive spesifikasjonen rett til kildekoden​

For GraphQL erfarer vi at dette kan være en effektiv måte å jobbe på, særlig dersom man bruker code review som samarbeidsform. Siden det aller meste av koden kan genereres, er sjansen stor for at vi klarer å skrive en spesifikasjon som kan gå mer eller mindre direkte inn i koden og ut i produksjon som kjørende API.

Erfaringen til nå tilsier også at det er forholdsvis lett å lære seg å skrive GraphQL-skjemaspråket, også for en ikke-utvikler. Det krever at du er litt teknisk anlagt, men det er et enklere språk enn for eksempel HTML.

For REST/OpenAPI er dette en mindre egnet strategi. For det første erfarer vi at yaml-kode er litt klønete og vanskelig å skrive riktig. For det andre, er det mye i REST-delen av FS-plattformen som ikke kan genereres direkte.

Skreddersydde redigeringsverktøy​

Til GraphQL har vi god erfaring med GraphQL Editor. Særlig er dette et godt støtteverktøy til designworkshops, ved at du får umiddelbar visualisering av endringer du gjør i grafen.

Du kan velge mellom to måter å redigere skjemaet på - enten ved å skrive direkte inn i koden, eller ved å bruke et innebygd pek-og-klikk-verktøy for å redigere eller legge til ting i skjemaet.

Til OpenAPI/REST har det ikke lyktes oss å finne et verktøy som passer til formålet, men det er en stund siden vi lette, så det kan ha endret seg.

Verktøy for visualisering av GraphQL-skjemaet​

Ett lettvektalternativ til GraphQL Editor er GraphQL Voyager. Lenken fører til en demoversjon, der du kan laste opp ditt eget GraphQL-skjema og få et fugleperspektiv på hvordan APIet ser ut underveis i en designøkt.

Excel​

Dersom vi ikke kan skrive skjemaet/spesifikasjonen direkte i det språket som skal inn i kildekoden, er faktisk Excel et godt alternativ. Vi har til nå foretrukket dette til spesifikasjon av REST/OpenAPI. Vi har brukt et excel-ark med følgende kolonner:

  • ObjektTypeNavn: Navn på typen/objektet feltet bor i
  • FeltNavn: Navn på feltet
  • K-FeltNavn: Navn på feltet i kjerneapiet (mapping)
  • DataType: Datatype. I GraphQL kan vi bruke dette feltet til å legge inn kanter
  • Merknad: Intern kommentar som ikke skal være med i APIet
  • Nullable: Om feltet kan ha nullverdier
  • Comments: Dokumentasjon av feltet som skal vises til brukeren
  • array: Om feltet skal være en liste
  • example: Eksempelverdi (brukes i OpenAPI-spesifikasjon)
  • format: Presisering av datatypen (brukes i OpenAPI-spesifikasjon)
  • pattern: Mulighet for å legge inn regEx som validerer inputverdi mot et bestemt mønster (f.eks. sjekker at det er en "ekte" e-postadresse)
  • readOnly: Hvorvidt feltet skal være sperret for skriving
  • enum: Hvis input skal begrenset til en gitt liste med verdier, skriv gyldige verdier her
  • minLength: Minimum-lengde for inputverdien
  • maxLength: Maksimum-lengede for inputverdien
  • maximum: Maksimumsverdi for feltet
  • minimum: Minimumsverdi for feltet
  • Deprecated: Hvorvidt feltet skal markeres som utgått

Vi har brukt designworkshop for å fylle ut dette excel-arket sammen, og så har resultatet blitt kopiert over i en Jira-sak som har vært brukt av utvikleren som implementerer saken. Vi har også lekt med tanken på at dette kan videreutvikles til et verktøy for å generere OpenAPI-spesifikasjon, men siden vi ganske raskt gikk over til å skrive GraphQL i GraphQL Editor, i kombinasjon med direkte redigering av skjemaet i kildekoden.