Lisää generaattoreita, kirjoitustyökaluja ja aineistoja tarinankerrontaan.
API-päätepisteiden nimeämisen tausta
Päätepisteiden nimet sijoittuvat tuotekielen ja toteutustietojen väliin. Hyvän päätepisteen otsikon tulisi kertoa tiimikaverille, mitä reitti tekee, ennen kuin kukaan avaa ohjaimen, spesifikaation tai muutoslokin. REST-tyyppisessä API:ssa sanamuodot tasapainottavat yleensä resurssien selkeyttä, metodin tarkoitusta, laajuutta, versiointia ja käyttösääntöjä. Nimi, kuten Fetch Export Job Status, viittaa erilaiseen ajatusmalliin kuin Run Old Billing Routine. Toinen kuulostaa rajoitetulta ja tarkistettavalta, kun taas toinen vihjaa vanhaan toimintovalikoimaan. Tämä generaattori tutkii sekä hiottuja että ongelmallisia malleja, jotta voit tunnistaa, mikä kuuluu julkiseen API:in, mikä kuuluu järjestelmänvalvojan portin taakse ja mikä pitäisi luultavasti nimetä uudelleen ennen kuin se saavuttaa asiakkaan.
Generoitujen päätepisteiden nimien käyttö
Yhdistä nimi todelliseen resurssiin
Aloita kysymällä, mikä substantiivi omistaa toiminnon. Käyttäjät, laskut, lataukset, istunnot, organisaatiot, viennit ja webhookit viittaavat kaikki erilaisiin käytäntöihin. Jos luotu nimi antaa sinulle oikean substantiivin, mutta väärän verbin, pidä substantiivi ja kirjoita toiminto uudelleen. Jos verbi tuntuu oikealta, mutta resurssi on epämääräinen, rajaa sitä, kunnes nimi olisi järkevä API-viittaustaulukossa.
Kunnioita laajuutta ja käyttöoikeuksia
Vain järjestelmänvalvojan käytettävissä olevat reitit, julkiset vain luku -reitit, taustatyön käynnistimet ja sisäiset työkalujen päätepisteet eivät saisi kuulostaa keskenään vaihdettavilta. Niiden nimiin liittyy operatiivinen riski. Tuhoavan toiminnon tulisi olla yksiselitteinen poistamisen, kumoamisen, puhdistamisen tai peruutuksen suhteen. Terveystarkistuksen tulisi kuulostaa havaittavalta, ei mutatoivalta. Webhook-takaisinkutsun tulisi tehdä saapuvasta tapahtumasta ilmeinen.
Pidä versiointi näkyvissä, kun sillä on merkitystä
Versioitettujen ja vanhentuneiden reittien on oltava nimiä, jotka auttavat tiimejä siirtymään. Käytä luotuja vanhentumisnimiä yhteensopivuuspäätepisteiden, vanhentumisvaroitusten, poistettujen kenttäkarttojen tai korvaavien esikatselujen merkitsemiseen. Tavoitteena ei ole koristeellinen nimeäminen. Tavoitteena on vähentää epäselvyyttä, kun vanhat asiakkaat, uudet asiakkaat ja sisäiset työkalut ovat päällekkäisiä.
Tiimikäytössä käsittele valittua nimeä sopimuksena koodin ja dokumentaation välillä. Jos nimi ei pysty selittämään resurssia, vaikutusta, käyttöoikeustasoa ja elinkaarta muutamalla sanalla, se todennäköisesti pyytää polkua, kaavaa tai spesifikaatiota tekemään liikaa korjaustyötä.
Käytännön vinkkejä nimen valintaan
- Suosi vahvaa resurssin substantiivia epämääräisen objektin, kuten kohteen, asian, datan tai tavaran, sijaan.
- Käytä verbejä, jotka vastaavat reitin toimintaa, erityisesti mutaatioissa, vienneissä ja taustatöissä.
- Merkitse järjestelmänvalvojan, sisäiset, vaaralliset tai vuokraajan laajuiset toiminnot selkeästi.
- Vältä nimiä, jotka kätkevät sivuvaikutuksia neutraalien sanojen, kuten prosessin tai toiminnon, taakse.
- Pidä webhook-nimet vastaanotettavan tai käsiteltävän tapahtuman keskipisteenä.
- Tarkista, onko nimi edelleen järkevä lokeissa, dokumentaatiossa ja tukitiedoissa.
Kehotteet päätepisteiden kielen tarkentamiseen
Kun tulos kiinnittää huomiosi, testaa sitä sitä ympäröivää API-pintaa vasten. Päätepisteiden nimet toimivat parhaiten perheinä, eivät erillisinä tunnisteina. Käytä näitä kysymyksiä muuttaaksesi karkean ehdokkaan käytännöksi, jota tiimisi voi toistaa.
- Mikä tarkalleen ottaen resurssi näkyisi polussa tai ohjaimessa tällä nimellä?
- Onko päätepiste vain luku -tilassa, mutatoiva, tuhoava, sisäinen, julkinen vai vuokraajakohtainen?
- Olisiko sama sanamuoto edelleen selkeä OpenAPI-yhteenvedossa?
- Paljastaako nimi riittävästi riskiä tietoturva- ja tukitiimeille?
- Voisiko tuleva versio säilyttää tämän mallin ilman hankalia poikkeuksia?
- Millä vierekkäisillä päätepisteillä tulisi olla sama verbi- tai substantiivimalli?
Miten API-päätepistegeneraattori toimii?
Se näyttää lyhyitä päätepisteitä API-kohtaisten linssien, kuten resurssien, laajuusalueiden, versioiden, webhookien, latausten, hakujen, töiden, terveystarkistusten ja tuhoavien toimintojen, ympärille kirjoitetut nimet. Jokainen napsautus antaa nimiä, jotka voit kopioida, mukauttaa tai yhdistää.
Voinko ohjata API-päätepistegeneraattoria tiettyyn nimikulmaan?
Kyllä. Rullaa uudelleen, kunnes kulma sopii API-pintaasi, ja sekoita sitten useita nimiä käytännöksi, joka sopii metodiisi, resurssiisi, laajuuteesi ja versiointimalliisi.
Ovatko nimet alkuperäisiä ja turvallisia käyttää?
Nimet on kirjoitettu tätä generaattoria varten ja niitä voidaan käyttää henkilökohtaisissa ja useimmissa kaupallisissa yhteyksissä. Säänneltyjen tuotteiden, julkisten API-rajapintojen tai brändikriittisten järjestelmien nimiä kannattaa silti verrata omiin standardeihisi.
Kuinka monta nimeä voin luoda?
Voit käynnistää generaattorin toistuvasti ja jatkaa ehdokkaiden keräämistä. Se on suunniteltu nopeaan tutkimiseen, joten voit vertailla yksinkertaisia REST-nimiä, järjestelmänvalvojan reittejä, webhookeja ja sisäisiä tunnisteita ilman kiinteän kiintiön seuraamista.
Miten tallennan haluamasi nimet?
Napsauta tulosta kopioidaksesi sen tai käytä sydän- tai tallennuskuvaketta säilyttääksesi pikaluettelon, kun vertailet reittiperheitä, nimeämiskäytäntöjä ja lopullista API-dokumentaation sanamuotoa.
Millaisia ovat hyvät API-päätepisteiden nimet?
Tässä generaattorissa on tuhansia satunnaisia API-päätepisteiden nimet. Aloita näistä esimerkeistä:
- 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
Tietoa tekijästä
Tarinankertoja ja kehittäjä Martin Hooijmans rakentaa huolella kaikki The Story Shackin ideageneraattorit ja kirjoitustyökalut. Päivisin työskentelen teknologiaratkaisujen parissa. Vapaa-ajallani uppoudun mielelläni tarinoihin lukemalla, kirjoittamalla, pelaamalla tai roolipelaamalla – luultavasti nautin melkein mistä tahansa tarinoihin liittyvästä. The Story Shack on tapani antaa takaisin maailmanlaajuiselle tarinankerrontayhteisölle. Se on valtava luova kanava, jossa saan herättää ideani eloon. Kiitos vierailustasi. Jos pidit tästä työkalusta, tutustu myös muutamaan muuhun!
Tallennetut ideat 
Akatemia
Estetiikka
Tekoälytyökalut
Kauneus
Olut
Yritykset
Call of Duty
Kalligrafia
Autot
Koodi
Kahvi
Cosplay
Cottagecore
Kodikas
Käsityöt
Muoti
Festivaalit
Ruoka
Käyttäjänimet
Juhlapyhät
Miksologia
Musiikki
Toimisto
Vanhemmuus
Juhlat
Podcastit
Tuottavuus
Ammatit
Projektinhallinta
Laivat
Urheilu
Tatuoinnit
Teknologiatapahtumat
Televisio
Twitch
Häät
Noituus
Showpaini