API pamati

Tālāk ir apkopotas pamata zināšanas par programmsaskarnes (API) jēgu, nepieciešamību, lietošanu, izveidošanu un drošību.

Saturs

• Kas ir API?
  • Kas ir REST API?
  • Kas ir GET, POST, DELETE pieprasījumi?
  • Kas ir Web API?
  • Kādi ir API veidi?
    • Privāti API
    • Publiski API
    • Partneru API
    • Apvienotie API
  • Kas ir API galapunkts?
  • Kā aizsargāt REST API?
• API pieprasījumu veidošana
  • Pamata URL un galapunkts
  • ?, =, & simboli Web API pieprasījumos
  • 200, 400 un citi statusa kodi
• API pieprasījumi JavasScript
  • fetch() izmantošana
  • Promise, async/await, .json()
• API izveidošana (NodeJS Express)
  • Express uzstādīšana
  • Servera sagatavošana
  • Servera darbības pārbaudīšana
  • Servera faila atjaunināšana
  • API galapunktu uzstādīšana
  • Pieprasījuma parametru saņemšana (req)
  • Pieprasījumu izdarīšana uz citiem API (ar Axios)

Kas ir API?

Programmsaskarnes jeb API (Application Programming Interface) ir sistēmas, kas ļauj diviem programmatūras komponentiem sazināties vienam ar otru, izmantojot definīciju un protokolu kopu jeb vienkāršākiem vārdiem, API ir veids kā divām programmām 'sazināties' - viena nosūta pieprasījumu, otra apstrādā pieprasījum un nosūta pretī atbildi. API dažreiz uzskata par līgumiem ar dokumentāciju, kas atspoguļo pušu vienošanos: ja 1. puse nosūta pieprasījumu, kas strukturēts noteiktā veidā, 2. puses programmatūra atbilstoši reaģēs.

Kas ir REST API?

Šī kursa ietvaros ar API tiks apzīmēts pamatā REST (Representational State Transfer) API veids. Tas darbojas tā, ka Klients (client) nosūta pieprasījumus serverim kā datus. Serveris izmanto šo klienta ievadi, lai palaistu iekšējās funkcijas un atgriež izejas datus atpakaļ klientam.

REST definē tādu funkciju kopu kā GET, POST, DELETE utt., kuras klienti var izmantot, lai piekļūtu servera datiem. Klienti un serveri apmainās ar datiem, izmantojot HTTP.

Galvenā REST API iezīme ir tāda, ka serveri nesaglabā klienta datus starp pieprasījumiem. Klientu pieprasījumi serverim ir līdzīgi URL adresēm, ko ievada pārlūkprogrammā, lai apmeklētu interneta vietni. Atbilde no servera ir vienkārši dati, bez tipiskas tīmekļa lapas grafiskās atveidošanas.

Kas ir GET, POST, DELETE pieprasījumi?

• GET pieprasījums ir veids, kā ar iegūt datus no datu avota.
• POST pieprasījumu izmanto, lai nosūtītu datus uz serveri, lai izveidotu/atjauninātu resursu.
• DELETE pieprasījumu izmanto, lai dzēstu norādīto resursu.

Kas ir Web API?

Web API vai Web Service API ir lietojumprogrammu apstrādes saskarne starp tīmekļa serveri un tīmekļa pārlūkprogrammu. Visi tīmekļa pakalpojumi ir API, bet ne visi API ir tīmekļa pakalpojumi. REST API ir īpašs tīmekļa API veids, kas izmanto iepriekš aprakstīto standarta arhitektūras stilu. Web API parasti atbides sniez XML vai JSON formātā.

Kādi ir API veidi?

API tiek klasificētas gan pēc to arhitektūras, gan pēc lietošanas jomas. Tālāk ir apskatīti API pēc izmantošanas jomas.

Privāti API

Tie ir uzņēmuma iekšēji API un tiek izmantoti tikai sistēmu un datu savienošanai uzņēmumā.

Publiski API

Tie ir pieejami publiski un tos var izmantot ikviens. Ar šāda veida API var būt vai nebūt zināma autorizācija un izmaksas.

Partneru API

Tie ir pieejami tikai pilnvarotiem ārējiem izstrādātājiem, lai palīdzētu uzņēmumu savstarpējām partnerībām.

Apvienotie API

Tie apvieno divas vai vairākas dažādas programmsaskarnes, lai risinātu sarežģītas sistēmas prasības vai darbības.

Kas ir API galapunkts?

API galapunkti ir saskares punkti API sistēmā. Tie pārsvarā ietver serveru URL adreses, no kurām informācija tiek nosūtīta un saņemta starp sistēmām. API galapunkti ir svarīgi divu galveno iemeslu dēļ.

Drošība

API galapunkti padara sistēmu neaizsargātu pret uzbrukumiem. API uzraudzība ir ļoti svarīga, lai novērstu ļaunprātīgu izmantošanu.

Veiktspēja

API galapunkti, īpaši tie, kuriem ir daudz vienlaicīgu pieprasījumu, var radīt vājās vietas un ietekmēt sistēmas veiktspēju.

Kā aizsargāt REST API?

Visām API ir jābūt aizsargātām, izmantojot pareizu autentifikāciju un uzraudzību. Divi galvenie veidi, kā aizsargāt REST API, ir autentifikācijas žetoni (authentication tokens) un API atslēgas.

Autentifikācijas žetoni

Žetoni tiek izmantoti, lai autorizētu lietotājus veikt API pieprasījumu. Tie pārbauda, vai lietotāji ir tie, par kuriem viņi uzdodas, un vai viņiem ir piekļuves tiesības konkrētajam API izsaukumam.

API atslēgas

API atslēgas verificē programmu vai lietotni, kas veic API pieprasījumu. Izmantojot atslēgu, sistēma identificē lietojumprogrammu un nodrošina, ka tai ir piekļuves tiesības, kas nepieciešamas konkrētā API izsaukuma veikšanai. API atslēgas nav tik drošas kā žetoni, taču tās ļauj veikt API uzraudzību, lai apkopotu datus par lietojumu.

API pieprasījumu veidošana

Pamata URL un galapunkts

API pamata URL adrese ir līdzīga kā jebkura pārlūkā ievadītā adrese, piemēram, https://programmesana2.lv/. Tomēr, kamēr nav pievienots konkrēts galapunktu, pamata API URL adrese neko daudz nedarīs.

Galapunkts ir īpašs API “ieejas punkts”. Pievienojot to pamata URL adreses beigām, var iegūt rezultātus atkarībā no izvēlētā galapunkta.

Piemēram, veicot izsaukumu pamata URL ar galapunktu https://programmesana2.lv/api/example/get, saņemsiet atbildi:

{
  "sveiciens": "Sveiks!"
}

?, =, & simboli Web API pieprasījumos

Vienkāršākajiem GET pieprasījumiem pēc galapunkta var pievienot papildus parametrus.

• ? jautājumzīmes simbolu izmanto lai norādītu, ka galapunkts ir beidzies un turpmāk sekos parametri;
• = vienādības simbolu izmanto lai norādītu, ka parametram tiek piešķirta vērtība;
• & and simbolu izmanto lai norādītu, ka viens parametrs un tā vērtība ir beidzies un sākas nākamais parametrs.

Piemēram, lai galapunktam pievienotu parametrus ar vērtībām vards=Reinis & uzvards=Ozols, var izveidot šādu pieprasījumu:

https://programmesana2.lv/api/example/get?vards=Reinis&uzvards=Ozols

API atbilde būs:

{
  "sveiciens": "Sveiks, Reinis Ozols!"
}

200, 400 un citi statusa kodi

HTTP izsaukuma statusa kods ir servera atbilde uz pieprasījumu. Kad tiek veikts pieprasījums uz kādu API, tā atbilde ietver statusa kodu. Biežākie statusa kodi:

Pilns saraksts ar iespējamiem HTTP statusu kodiem.

API pieprasījumi JavasScript

Lai veiktu API izsaukumu no JavaScript, var izmantot iebūvētās metodes un īpašības.

fetch() izmantošana

JavaScript metodi fetch() izmanto, lai pieprasītu datus no servera. Pieprasījums var būt jebkura veida API, kas atgriež datus JSON vai XML formātā. Metodei fetch() ir nepieciešams padot vienu parametru, API izsaukuma URL, kas jāpieprasa, un tā atgriež solījumu (Promise).

Promise, async/await, .json()

Solījumi (Promise) tiek izmantoti, lai apstrādātu asinhronas darbības JavaScript. Asinhronas darbības vienkāršoti nozīmē, ka būs jāpagaida kāds laiks, lai apstrādātu pieprasījumu un atgrieztu rezultātu. Tāpēc Promise šādi stāvokļi:

• gaida (pending): Promise joprojām nav izpildīts, t.i., vēl nav izpildīts vai noraidīts;
• izpildīts (fulfilled): darbība saistībā ar Promise izdevās;
• noraidīts (rejected): darbība saistībā ar Promise neizdevās;

Lai javascript funkcijā izmantotu Promise, definējot funkciju nepieciešams to norādīt ar async atslēgvārdu un pirms asinhronās darbības lietot await atslēgvārdu, norādot, ka nepieciešams pagaidīt, līdz Promise atrisinās.

Visbiežāk API atgriezīs atbildi JSON formātā, bet lai to nolasītu un tālāk izmantotu JavaScript, vispirms to ir nepieciešams atbildi pārviedot JS objektā, izmantojot .json() metodi,

Piemēram, ja ir jāsagaida dati no kāda API, tad funkciju varētu definēt šādi:

async function iegutDatus() {
  const atbilde = await fetch("https://api.piemers.com/iegut-datus");
  const dati = await atbilde.json();
}

API izveidošana (NodeJS Express)

Lai izveidotu paši savu programssaskarni jeb API, būs nepieciešams izstrādāt servera puses (backend) loģiku, kas apstrādās ienākušos pieprasījumus. Šī kursa ietvaros servera puses mēs izmantosim Express, kas ir Node.js tīmekļa ietvars (framework) un tas ir paredzēts tīmekļa lietojumprogrammu un API izveidei.

Express uzstādīšana

Lai uzstādītu Express, vispirms ir nepieciešams Node un NPM (palšāk aprakstīts šeit). Darbības soļi, lai uzsāktu jaun Express projektu:

1. ar komandu npm init uzsākam jaunu Node projektu;
2. svarīgi ir solī entry point norādīt servera datnes nosaukumu, piemēram, server.js vai api.js;
3. izveidosies jauna datne package.json - šis fails ir jebkura Node projekta centrālā datne, jo tajā tiek definēti projekta funkcionālie atribūti, ko NPM izmanto, lai instalētu pakotnes, palaistu skriptus un identificētu ieejas punktu.
4. Ar NPM pievienot Express un CORS pakotnes
   1. npm install express
   2. npm install cors

Servera sagatavošana

Šeit būs skaidrojums un paraugs, kā definēt Express un uzstādīt vienkāršakos galapunktus.

Vispirms servera failam (piemēram, server.js) nepieciešams pievienot express un cors pakotnes. CORS pakotne ir NodeJS pakotne Express starpprogrammatūras (middleware) nodrošināšanai, ko var izmantot, lai iespējotu CORS ar dažādām opcijām.

Cross-Origin Resource Sharing jeb CORS ir sistēma, kas ļauj serverim norādīt jebkuru citu izcelsmi (domēnu, shēmu vai portu), no kuras pārlūkprogrammai ir jāatļauj ielādēt resursus. Drošības apsvērumu dēļ pārlūkprogrammas ierobežo starpizcelsmes HTTP pieprasījumus, kas iniciēti no skriptiem. Detalizēta CORS politikas lietošana ir ārpus šī kursa ietvariem, tādēļ turpmākajos lietosim CORS, kas atļauj visus pieprasījumus, tomēr izstrādājot sarežģītākas sistēmas, noteikti būtu jāņem vērā riski.

//pievienot pakotnes
const express = require("express");
var cors = require("cors");
//aktivizēt Express
const app = express();
//lietot CORS
app.use(cors());

Servera darbības pārbaudīšana

Lai pārbaudītu, vai servera fails ir sagatavots pareizi, nepieciešams to pārbaudīt.

1. Definēt port, kuru serverim klausīties;
2. Izmantot app.listen() metodi, lai sasaistītu un klausītos savienojumus norādītajā resursdatorā un portā.
3. Aktivizēt servera failu.

Servera failā (server.js) tas izskatītos:

const port = 3000;
app.listen(port, function (req, res) {
  console.log(`Server is running at port ${port}`);
});

Lai aktivizētu servera failu (server.js), terminālī jāieraksta komdanda

node server.js

Ja servera fails ir pareizi uzstādīts, tad no šī piemēra terminālī parādīsies izdruka:

Server is running at port 3000

Servera faila atjaunināšana

Ja servera failā tiek veiktas kādas izmaiņas, tad terminālī vispirms failu jādeaktivizē ar Ctrl + C un tad atkal jāaktivizē, piemēram, node server.js.

Kā alternatīvu var izmantot nodemon pakotni, kas automātiski atjauno servera failu, ja tas tiek modificēts.

Lai aktivizētu servera failu ar nodemon, terminālī jāieraksta komanda

npx nodemon server.js

API galapunktu uzstādīšana

Lai izveidotu GET galapunktu, var izmantot .get() metodi, kas saņem divus parametrus:

1. galapunkta adresi;
2. Izpildes funkciju, kas izpildās, kad veikts pieprasījums uz (1.) adresi;

Izpildes funkcija (2.) satur 2 argumentus piepraīsjums (req) un atbilde (res)

3. req satur pieprasījuma informāciju, ieskaitot parametrus un vērtības, ja tādi ir padoti;
4. res izmanto, lai ietkļautu informāciju, ko atgriezt pieprasītājam.

Piemēram:

app.get("/piemers", function (req, res) {
  res.json({
    route: "route ir '/piemers'",
  });
});

1. galapunkts ir /piemers
2. izpildes funkcija atgriež atbildi
3. ar res.json(...) metodi, kas nosūta atbildi pārvēstu JSON formātā.

Šajā piemērā izveidojot pieprasījum uz galapunktu /piemers, tiks saņemta atbilde:

{ route: "route ir '/piemers'" }

Lai API saprastos ar pieprasītāju (client), svarīgi ir padot arī statusu. Tam izmanto metodi .status().

//padot 200 statusa kodu
res.status(200);

//padot 400 statusa kodu
res.status(400);

Pieprasījuma parametru saņemšana (req)

Pieprasījums req ietver dažādus parametrus. Bieži tas satur arī atslēgu vai argumentus un vērtības, ko vēlāk nepieciešams izmantot, lai apstrādātu pieprasījumu. Šie parametri atrodas īpašībā .query

const query = req.query;

Piemēram

app.get("/piemers-ar-parametriem", function (req, res) {
  const query = req.query;
  res.json({
    route: "route ir '/piemers-ar-parametriem'",
    parametri: query,
  });
});

izveidojot pieprasījumu uz piemēra galapunktu /piemers-ar-parametriem?paraugs=true&valoda=lv, saņemtu atbildi

{
  route: "route ir '/piemers-ar-parametriem'",
  parametri: {
    paraugs: "true",
    valoda: "lv"
  }
}

Pieprasījumu izdarīšana uz citiem API (ar Axios)

Lai no servera puses izdarītu pieprasījumu uz kādu citu API, var izmantot pakotni axios. Līdzīgi kā fetch() no pārlūka, ar Axios var izveidot asinhronu HTTP pieprasījumu uz kādu API galapunktu.

const response = await axios.get(`https://example.api/gateway?language=en`);