API-suunnittelun periaatteet ja parhaat käytännöt
Oppikaa suunnittelemaan selkeitä, yhdenmukaisia ja ylläpidettäviä RESTful-rajapintoja keskittyen resurssikeskeiseen arkkitehtuuriin.
API-suunnittelun periaatteet ja parhaat käytännöt on ilmainen Elixir ja Phoenix: skaalautuva backend-kehitys-oppitunti CoddyKitissä. Tämä on oppitunti 1/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu Elixir ja Phoenix: skaalautuva backend-kehitys-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Elixir ja Phoenix: skaalautuva backend-kehitys-kurssilla on yhteensä 4 oppituntia.
Tervetuloa API-suunnittelun pariin!
Tervetuloa kurssimme "RESTful APIen rakentaminen Phoenixilla" ensimmäiselle oppitunnille! Hyvin suunniteltu API on ratkaisevan tärkeä skaalautuvien ja helposti ylläpidettävien sovellusten rakentamisessa.
Tällä oppitunnilla perehdymme selkeiden, johdonmukaisten ja helppokäyttöisten RESTful APIen suunnittelun perusperiaatteisiin ja parhaisiin käytäntöihin. Aloitetaan!
Mikä on RESTful API?
REST (Representational State Transfer) on verkkosovellusten arkkitehtuurityyli. RESTful API noudattaa seuraavia periaatteita:
- Asiakas–palvelin: Vastuualueet on erotettu toisistaan.
- Tilattomuus: Jokaisen asiakkaalta palvelimelle tulevan pyynnön on sisällettävä kaikki tarvittavat tiedot.
- Välimuistitettavuus: Vastaukset voidaan tallentaa välimuistiin suorituskyvyn parantamiseksi.
- Kerrostettu järjestelmä: Asiakas ei voi tietää, onko se yhteydessä suoraan kohdepalvelimeen vai välipalvelimeen.
- Yhtenäinen rajapinta: RESTin ydin, joka yksinkertaistaa vuorovaikutusta.
Kyse on resurssien käsittelystä HTTP:n vakiomenetelmillä.
Resurssilähtöinen ajattelu
RESTin ytimessä on resurssin käsite. Ajatelkaa kaikkea API:n tarjoamaa resurssina. Resurssit yksilöidään yleensä yksilöllisillä URL-osoitteilla.
Toimintojen (kuten 'getProduct' tai 'deleteUser') sijaan ajatelkaa itse dataa (kuten 'product' tai 'user').
Jos esimerkiksi rakennatte verkkokaupan API:a, resursseja voivat olla:
- Tuotteet
- Tilaukset
- Asiakkaat
- Luokat
Jokaisella resurssilla on yksilöllinen tunniste, ja sillä voi olla erilaisia esitysmuotoja (esimerkiksi JSON tai XML).
Johdonmukaisten URL-osoitteiden suunnittelu
API:n URL-osoitteiden (eli päätepisteiden) tulee olla intuitiivisia ja ennakoitavia. Tässä muutamia hyviä käytäntöjä:
- Käyttäkää monikkomuotoisia substantiiveja: Kokoelmille (esimerkiksi
/products, ei/product). - Käyttäkää substantiiveja, älkää verbejä: URL-osoitteiden tulee yksilöidä resurssit, ei toimintoja (esimerkiksi
/users, ei/getAllUsers). - Muodostakaa hierarkioita: Tuokaa suhteet näkyviin (esimerkiksi
/users/123/orders). - Pidättehän rakenteen yksinkertaisena: Välttäkää tarpeetonta monimutkaisuutta.
Johdonmukaisuus tekee API:sta helpommin ymmärrettävän ja käytettävän.
HTTP-metodit: verbit
HTTP-metodit (joita kutsutaan myös verbeiksi) kertovat palvelimelle, mitä toimintoa resurssille suoritetaan. Niiden oikea yhdistäminen toimintoihin on RESTful-suunnittelun perusta.
- GET: Hakee dataa (turvallinen, idempotentti).
- POST: Luo uutta dataa (ei idempotentti).
- PUT: Korvaa olemassa olevan datan (idempotentti).
- PATCH: Päivittää olemassa olevaa dataa osittain (ei idempotentti).
- DELETE: Poistaa dataa (idempotentti).
Idempotentti tarkoittaa, että saman pyynnön lähettäminen useita kertoja tuottaa saman vaikutuksen kuin sen lähettäminen kerran (esimerkiksi resurssin poistaminen useita kertoja johtaa silti siihen, että se poistetaan vain kerran).
HTTP:n vakiotilakoodit
HTTP-tilakoodit kertovat API-pyynnön tuloksen. Niiden oikea käyttö on olennaista selkeyden ja vianmäärityksen kannalta.
- 2xx Onnistuminen:
200 OK,201 Created,204 No Content. - 4xx Asiakasvirhe:
400 Bad Request,401 Unauthorized,403 Forbidden,404 Not Found,409 Conflict. - 5xx Palvelinvirhe:
500 Internal Server Error,503 Service Unavailable.
Palauttakaa aina mahdollisimman täsmällinen tilakoodi, jotta asiakkaat ymmärtävät, mitä tapahtui.
API:n dataformaatit: JSON
JSON (JavaScript Object Notation) on API-pyyntöjen ja -vastausten sisältöjen de facto -standardi keveytensä ja helppolukuisuutensa ansiosta.
Varmistakaa, että API käyttää johdonmukaisesti JSON-muotoa tiedonsiirtoon. Yksinkertainen Elixir-kartta voi esittää tuotteen JSON-vastauksen esimerkiksi näin:
defmodule ProductAPI do
def get_product(id) do
# In a real API, this would fetch from a database
case id do
"prod_xyz" ->
%{
id: "prod_xyz",
name: "Wireless Headphones",
price: 99.99,
currency: "USD",
in_stock: true
}
_ ->
nil
end
end
end
IO.inspect(ProductAPI.get_product("prod_xyz"))Kyselyparametrien käsittely
Kyselyparametrien avulla asiakkaat voivat suodattaa, lajitella ja sivuttaa resurssikokoelmia. Ne näkyvät URL-osoitteessa ?-merkin jälkeen (esimerkiksi /products?category=electronics&sort=price).
Seuraava yksinkertainen Elixir-funktio havainnollistaa kyselymerkkijonon käsittelyä (Phoenix hoitaa tämän puolestanne, mutta esimerkki näyttää periaatteen):
defmodule QueryParser do
def parse(query_string) do
query_string
|> String.split("&")
|> Enum.map(fn pair ->
[key, value] = String.split(pair, "=")
{String.to_atom(key), value}
end)
|> Enum.into(%{})
end
end
query_params = QueryParser.parse("category=books&sort=title&limit=10")
IO.inspect(query_params)API:n versiointistrategiat
API:n kehittyessä siihen on tehtävä muutoksia. Versiointi estää olemassa olevien asiakassovellusten rikkoutumisen.
Yleisiä strategioita ovat:
- URL-versiointi: Sisällyttäkää versio URL-osoitteeseen (esimerkiksi
/v1/products). Tämä on yksinkertaista ja selkeää, mutta muuttaa URL-osoitetta. - Otsakeversiointi: Sisällyttäkää versio HTTP-otsakkeeseen (esimerkiksi
Accept: application/vnd.myapi.v2+json). Tämä on joustavampaa, mutta vähemmän näkyvää.
Valitkaa strategia ajoissa ja noudattakaa sitä johdonmukaisesti. URL-versiointia suositaan usein sen yksinkertaisuuden vuoksi.
Johdonmukaiset virhevastaust
Virhetilanteissa API:n tulee palauttaa selkeät ja johdonmukaiset virheilmoitukset. Tämä auttaa asiakkaita selvittämään ongelmat nopeasti.
Hyvä virhevastaus sisältää yleensä:
- Selkeän virhekoodin tai -tyypin.
- Ihmisen luettavissa olevan viestin.
- Valinnaisia lisätietoja (esimerkiksi tiettyjen kenttien validointivirheitä).
Tässä on esimerkki rakenteisen virhevastausen Elixir-kartasta:
defmodule ErrorFormatter do
def format_error(status, code, message, details \\ %{}) do
%{
status: status,
code: code,
message: message,
details: details
}
end
end
error_response = ErrorFormatter.format_error(
400,
"invalid_input",
"Validation failed",
%{email: "must be a valid email format"}
)
IO.inspect(error_response)Suunnitteluperiaatteiden haaste
Mikä seuraavista API-päätepisteiden rakenteista noudattaa parhaiten RESTful-periaatteita käyttäjäluettelon hakemiseen?
Kertaus: tärkeimmät suunnitteluopit
Hienoa työtä! Olette käyneet läpi vankkojen ja helposti ylläpidettävien RESTful APIen suunnittelun olennaiset periaatteet.
- Ajatelkaa resursseina (substantiiveina, ei verbeinä).
- Käyttäkää johdonmukaisia URL-osoitteita ja monikkomuotoisia substantiiveja.
- Yhdistäkää HTTP-metodit (GET, POST, PUT, PATCH, DELETE) toimintoihin oikein.
- Palauttakaa asianmukaiset HTTP-tilakoodit.
- Käyttäkää JSONia pyyntöjen ja vastausten sisältöihin.
- Toteuttakaa kyselyparametrit datan käsittelyä varten.
- Suunnitelkaa API:n versiointi.
- Tarjotkaa johdonmukaiset virhevastauset.
Nämä periaatteet ohjaavat teitä rakentamaan API:eja, joita on helppo ymmärtää, käyttää ja kehittää. Seuraavaksi toteutamme nämä suunnitelmat Phoenixilla!
Opi Elixir tekoälytuutorin avulla — ilmaiseksi
Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.
- Kurssit
- 12
- Oppitunnit
- 48
Usein kysytyt kysymykset
Onko oppitunti ”API-suunnittelun periaatteet ja parhaat käytännöt” ilmainen?
Kyllä – oppitunnin ”API-suunnittelun periaatteet ja parhaat käytännöt” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko Elixir ja Phoenix: skaalautuva backend-kehitys-kurssin, päivitä CoddyKit PROhon. Elixir ja Phoenix: skaalautuva backend-kehitys-kurssilla on yhteensä 4 oppituntia.
Mitä opin oppitunnilla ”API-suunnittelun periaatteet ja parhaat käytännöt”?
Oppikaa suunnittelemaan selkeitä, yhdenmukaisia ja ylläpidettäviä RESTful-rajapintoja keskittyen resurssikeskeiseen arkkitehtuuriin. Harjoittelet Elixir ja Phoenix: skaalautuva backend-kehitys-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.
Tarvitsenko kokemusta aloittaakseni Elixir ja Phoenix: skaalautuva backend-kehitys-opiskelun?
Aiempi kokemus ei ole tarpeen. CoddyKitin Elixir ja Phoenix: skaalautuva backend-kehitys-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 1/4.
Kuinka kauan ”API-suunnittelun periaatteet ja parhaat käytännöt”-oppitunnin suorittaminen kestää?
Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.
Voinko kirjoittaa ja suorittaa koodia tällä Elixir ja Phoenix: skaalautuva backend-kehitys-oppitunnilla?
Kyllä. Jokainen Elixir ja Phoenix: skaalautuva backend-kehitys-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.
Kaikki tämän kurssin oppitunnit
- API-suunnittelun periaatteet ja parhaat käytännöt
- API-päätepisteiden ja serialisoinnin toteuttaminen
- Todennus- ja valtuutusstrategiat
- Sivutus, suodatus ja API-versiointi