API-endepunktnavngenerator

Bakgrunn for navngiving av API-endepunkter

Endepunktnavn ligger mellom produktspråk og implementeringsdetaljer. En god endepunktetikett bør fortelle en teammedlem hva ruten gjør før noen åpner kontrolleren, spesifikasjonen eller endringsloggen. I et REST-stil API balanserer ordlyden vanligvis ressursklarhet, metodeintensjon, omfang, versjonering og tilgangsregler. Et navn som Hent eksportjobbstatus peker på en annen mental modell enn Kjør gammel faktureringsrutine. Det ene høres avgrenset og gjennomgåelig ut, mens det andre hinter til en eldre handlingspakke. Denne generatoren utforsker både polerte og problematiske mønstre, slik at du kan gjenkjenne hva som hører hjemme i et offentlig API, hva som hører hjemme bak en administrasjonsport, og hva som sannsynligvis bør gis nytt navn før det når en klient.

Slik bruker du genererte endepunktnavn

Kortlegg navnet til en reell ressurs

Start med å spørre hvilket substantiv som eier handlingen. Brukere, fakturaer, opplastinger, økter, organisasjoner, eksporter og webhooks antyder alle forskjellige konvensjoner. Hvis et generert navn gir deg riktig substantiv, men feil verb, behold substantivet og skriv handlingen på nytt. Hvis verbet føles riktig, men ressursen er vag, kan du begrense det til navnet gir mening i en API-referansetabell.

Respekter omfang og tilgang

Administratorruter, offentlige skrivebeskyttede ruter, bakgrunnsjobbutløsere og interne verktøysluttpunkter skal ikke høres utskiftbare ut. Navnene deres medfører driftsrisiko. En destruktiv handling skal være eksplisitt om sletting, tilbakekalling, tømming eller kansellering. En helsesjekk skal høres observerbar ut, ikke muterende. En webhook-tilbakekall skal gjøre den innkommende hendelsen åpenbar.

Hold versjonering synlig når det er viktig

Versjonerte og utdaterte ruter trenger navn som hjelper team med å migrere. Bruk genererte utdaterte navn for å merke kompatibilitetssluttpunkter, solnedgangsvarsler, fjernede feltkart eller erstatningsforhåndsvisninger. Målet er ikke dekorativ navngiving. Målet er å redusere tvetydighet når gamle klienter, nye klienter og interne verktøy overlapper hverandre.

For teambruk, behandle det valgte navnet som en kontrakt mellom kode og dokumentasjon. Hvis navnet ikke kan forklare ressursen, effekten, tilgangsnivået og livssyklusen med noen få ord, ber det sannsynligvis banen, skjemaet eller spesifikasjonen om å gjøre for mye reparasjonsarbeid.

Praktiske tips for å velge et navn

• Foretrekk et sterkt ressurssubstantiv fremfor et vagt objekt som element, ting, data eller ting.
• Bruk verb som samsvarer med ruteoppførselen, spesielt for mutasjoner, eksport og bakgrunnsjobber.
• Merk admin-, intern-, farlig- eller leietaker-omfattede operasjoner tydelig.
• Unngå navn som skjuler bivirkninger bak nøytrale ord som prosess eller handling.
• Hold webhook-navn sentrert rundt hendelsen som mottas eller håndteres.
• Sjekk om navnet fortsatt gir mening i logger, dokumentasjon og støttenotater.

Spørsmål om forbedring av endepunktspråk

Når et resultat fanger oppmerksomheten din, test det mot API-overflaten rundt det. Endepunktnavn fungerer best som familier, ikke isolerte etiketter. Bruk disse spørsmålene til å gjøre en grov kandidat om til en konvensjon teamet ditt kan gjenta.

• Hvilken nøyaktig ressurs ville vises i banen eller kontrolleren for dette navnet?
• Er endepunktet skrivebeskyttet, muterende, destruktivt, internt, offentlig eller leietaker-scope?
• Ville den samme ordlyden fortsatt være tydelig i et OpenAPI-sammendrag?
• Avslører navnet nok risiko for sikkerhets- og supportteam?
• Kan en fremtidig versjon beholde dette mønsteret uten vanskelige unntak?
• Hvilke nærliggende endepunkter bør dele samme verb- eller substantivmønster?

Hva er gode API-endepunktnavn?

Det finnes tusenvis av tilfeldige API-endepunktnavn i generatoren. Her er noen eksempler å begynne med:

• Create Customer Profile
• List Project Comment Threads
• Admin Suspend User Login
• Browse Public Catalog
• Bulk Import Customer Records
• Receive Payment Settled Webhook
• Fetch Deprecated V1 Profile
• Begin OAuth Authorization
• Export Daily Usage Metrics
• Create Direct Upload URL