EDUCATION · API · STANDARTI

🔌 API ceļvedis - projektēšana, drošība un infrastruktūra

Sešas sadaļas par lietojumprogrammu saskarnēm (API) atbilstoši starptautiskajai praksei: REST principi (Roy Fielding, 2000), HTTP metodes un statusa kodi (RFC 9110), drošība (OWASP API Top 10, OAuth 2.0, JWT), API vārtejas, reverse proxy un slodzes balansētāja atšķirības, dizaina prakses (RFC 9457, OpenAPI 3.1) un standartu atsauces. Piemēri ir ilustratīvi un paredzēti mācību nolūkiem.

Kas ir API

REST arhitektūras stils - Roy Fielding (2000)

API (Application Programming Interface) ir formāli definēts saskarnes līgums starp divām programmatūras komponentēm, kas nosaka, kā tās apmainās ar datiem. Tīmekļa API parasti balstās uz HTTP protokolu un REST arhitektūras stilu: resursus adresē ar URL, darbības izsaka ar HTTP metodēm, bet dati visbiežāk tiek pārraidīti JSON formātā.

Klients–serveris

Saskarne nodala klientu (saskarsmes slānis) no servera (datu glabāšana un loģika), ļaujot tos izstrādāt un mērogot neatkarīgi.

Bezstāvokļa

Katrs pieprasījums satur visu izpildei nepieciešamo kontekstu. Serveris neuztur klienta sesijas stāvokli, kas vienkāršo horizontālo mērogošanu.

Kešojamība

Atbildes nepārprotami marķē kā kešojamas vai nekešojamas (Cache-Control, ETag), samazinot servera slodzi un atbildes aizkavi.

Vienota saskarne

Vienoti mijiedarbības principi: resursu identifikācija, to attēlojumi (piem., JSON), pašaprakstoši ziņojumi un hipersaites (HATEOAS).

Slāņota sistēma

Starp klientu un serveri var atrasties starpniekslāņi (reverse proxy, gateway, kešs), klientam par tiem nezinot.

Kods pēc pieprasījuma

Neobligāts princips: serveris var nosūtīt izpildāmu kodu (piem., JavaScript), īslaicīgi paplašinot klienta funkcionalitāti.

REST

Resursorientēts arhitektūras stils virs HTTP. Vienkāršs un kešojams; dominē publiskajos tīmekļa API.

GraphQL

Viens endpoint; klients pieprasa tieši nepieciešamos laukus. Mazina pārmērīgu un nepietiekamu datu ielādi.

gRPC

Binārs, augstas veiktspējas RPC ietvars (Protocol Buffers, HTTP/2). Piemērots iekšējai mikroservisu saziņai.

WebSocket / SOAP

WebSocket - pastāvīgs divvirzienu reāllaika kanāls; SOAP - vecāks XML protokols ar stingri definētu līgumu (WSDL).

RFC 9110 - HTTP Semantics

Metodes (droša / idempotent) un statusa kodi

Metode	Droša	Idempotent	Kešojama	Tipiskais pielietojums
GET	✔	✔	✔	Nolasa resursu bez blakusefektiem
HEAD	✔	✔	✔	Atgriež tikai galvenes, bez ķermeņa
POST	✗	✗	reti	Izveido resursu vai palaiž darbību
PUT	✗	✔	✗	Pilnībā aizvieto resursu
PATCH	✗	✗	✗	Daļēji atjaunina resursu
DELETE	✗	✔	✗	Dzēš resursu
OPTIONS	✔	✔	✗	Atbalstītās metodes; CORS priekšpārbaude

Droša (safe)

Nemaina servera stāvokli; tikai nolasa datus. GET, HEAD, OPTIONS.

Idempotent

Viena un tā paša pieprasījuma atkārtošana rada tieši to pašu galarezultātu kā viens izsaukums. Būtiski drošai atkārtošanai pēc tīkla kļūmes.

POST nav idempotent

Atkārtots POST var radīt dublikātus. Risinājums - Idempotency-Key galvene (skat. sadaļu Dizaina prakses).

OWASP API Security Top 10:2023 · OAuth 2.0 · JWT

Autentifikācija, autorizācija un izplatītākie API riski

API drošības pamatā ir skaidra autentifikācijas (identitātes apliecināšana) un autorizācijas (piekļuves tiesību noteikšana) nošķiršana. Tīmeklī standarta risinājums ir OAuth 2.0 ar piekļuves tokeniem (parasti JWT), kurus pārbauda katrā pieprasījumā.

API atslēgas

Vienkārša servisa identifikācija. Nedrīkst nonākt klienta pusē vai koda repozitorijā; regulāri jāmaina (rotācija).

OAuth 2.0 / OIDC

Deleģēta autorizācija ar tokeniem; OIDC papildina to ar identitātes slāni (lietotāja autentifikācija).

JWT

Kriptogrāfiski parakstīts token trīs daļās: header.payload.signature. Vienmēr jāpārbauda paraksts, izdevējs (iss) un derīguma termiņš (exp).

mTLS

Abpusēja TLS - gan klients, gan serveris uzrāda sertifikātus. Spēcīga savstarpējā autentifikācija starp servisiem.

API1

BOLA

Objektu līmeņa autorizācijas trūkums - lietotājs piekļūst cita subjekta objektam, manipulējot ar identifikatoru (piem., /rekini/123). Visbiežākais API risks.

API2

Nepilnīga autentifikācija

Vāji vai nepareizi validēti token, nepārbaudīts paraksts, neierobežots pieteikšanās mēģinājumu skaits.

API3

BOPLA

Objektu īpašību līmeņa autorizācijas trūkums - pārmērīga datu atklāšana atbildē vai neatļauta masveida piešķiršana (mass assignment).

API4

Neierobežots resursu patēriņš

Trūkst apjoma un ātruma limitu - tas pieļauj pakalpojuma atteices (DoS) un infrastruktūras izmaksu pieaugumu.

API5

BFLA

Funkciju līmeņa autorizācijas trūkums - parasts lietotājs piekļūst administratīvām funkcijām.

API6

Jutīgas biznesa plūsmas

Neierobežota piekļuve jutīgām biznesa plūsmām - automatizēta ļaunprātīga izmantošana (piem., masveida biļešu uzpirkšana).

API7

SSRF

Servera puses pieprasījumu viltošana - serveris izpilda pieprasījumu uz uzbrucēja kontrolētu URL, sasniedzot iekšējos resursus.

API8

Drošības konfigurācijas trūkumi

Iztrūkstošas drošības galvenes, pārlieku atvērts CORS, detalizēti kļūdu paziņojumi.

API9

Nepietiekama inventāra pārvaldība

Aizmirstas vai novecojušas versijas un testa vides paliek publiski pieejamas un nedrošas.

API10

Nedroša patērēšana

Nekritiska uzticēšanās trešo pušu API datiem bez validācijas un ierobežojumiem.

Infrastruktūra priekšā API

API vārteja vs reverse proxy vs slodzes balansētājs

Visi trīs atrodas starp klientu un backend, tāpēc tos mēdz sajaukt. Patiesībā tie ir viena pamatkoncepta - reverse proxy - paveidi, kas specializējas atšķirīgās funkcijās. Praksē to robežas pārklājas, un bieži tie darbojas vienlaikus.

Aspekts	Reverse proxy	Slodzes balansētājs	API vārteja
Galvenais mērķis	Pārsūta pieprasījumus uz backend, slēpj tā topoloģiju	Sadala trafiku pa vairākām servera instancēm	Pārvalda API - vienots ieejas punkts mikroservisiem
OSI slānis	L7 (var arī L4)	L4 (transports) vai L7	L7 (lietojums)
Maršrutē pēc	Host / ceļa	IP / ports (L4) vai saturs (L7)	API ceļa, versijas, patērētāja
TLS terminācija	Jā	Jā (L7)	Jā
Autentifikācija / autorizācija	Pamata (iespējams WAF)	Nē	Jā - OAuth / JWT / API atslēgas (galvenā loma)
Rate-limit / kvotas	Ierobežoti	Nē	Jā (galvenā loma)
Health checks	Reti	Jā (galvenā loma)	Bieži (caur balansētāju)
Transformācija / agregācija	Nē	Nē	Jā - REST↔gRPC, vairāku servisu apvienošana
Tipiski rīki	Nginx, Apache, HAProxy, Envoy	HAProxy, Nginx, AWS NLB/ALB, F5	Kong, Apigee, AWS API Gateway, Azure APIM, Tyk

Reverse proxy

Pamatkoncepts - serveris klienta priekšā, kas pārsūta pieprasījumus uz backend. Nodrošina TLS termināciju, kešošanu, kompresiju un topoloģijas slēpšanu. Pārējie divi ir tā specializācijas.

Slodzes balansētājs

Reverse proxy, kas specializējas trafika sadalē (round-robin, least-connections) un pieejamībā - ar health checks un sticky sesijām.

API vārteja

Reverse proxy, kas specializējas API pārvaldībā: autentifikācija, rate-limit, versionēšana, transformācija, agregācija un novērojamība. Parasti tā ietver arī slodzes balansēšanu.

Praksē

Tipiska secība: klients → DNS/CDN → slodzes balansētājs → API vārteja → mikroservisi. Robežas pārklājas, un viens rīks bieži pilda vairākas lomas.

Labās prakses · RFC 9457 · OpenAPI 3.1

Versionēšana, limiti, kļūdas un līguma apraksts

/v1/

Versionēšana

Pa URL (/v1/...), galveni vai mediju tipu. Esošo versiju saderību nedrīkst lauzt - jāpievieno jauna versija.

page

Pagination

Lielus sarakstus dala lapās ar offset/limit vai kursora metodi. Vienmēr jāierobežo maksimālais lapas apjoms.

429

Rate limiting

Pieprasījumu ātruma ierobežošana ar atbildi 429 Too Many Requests un Retry-After galveni. Aizsargā pret pārslodzi un ļaunprātīgu izmantošanu.

key

Idempotency-Key

Idempotency-Key galvene POST izsaukumos novērš dublikātus, ja pieprasījumu atkārto pēc tīkla kļūmes.

9457

Vienots kļūdu formāts

RFC 9457 Problem Details - mašīnlasāma JSON kļūdas struktūra (type, title, status, detail).

OAS

OpenAPI 3.1

Mašīnlasāms API līgums - ģenerē dokumentāciju, klientu kodu un validāciju. Vienots patiesības avots saskarnei.

Kļūdas atbilde - RFC 9457 Problem Details

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30

{
  "type":   "https://api.piemers.lv/kludas/rate-limit",
  "title":  "Pārāk daudz pieprasījumu",
  "status": 429,
  "detail": "Limits 100 pieprasījumi minūtē ir pārsniegts.",
  "instance": "/v1/lietotaji"
}

Atsauces

Starptautiskie standarti un specifikācijas

RFC 9110HTTP Semantics - metodes, statusa kodi, galvenes2022 RFC 9111HTTP Caching - kešošanas semantika2022 RFC 6749OAuth 2.0 Authorization Framework2012 RFC 6750OAuth 2.0 Bearer Token Usage2012 RFC 7519JSON Web Token (JWT)2015 RFC 7636PKCE - publisku klientu aizsardzība2015 RFC 9457Problem Details for HTTP APIs2023 RFC 6585Papildu HTTP statusa kodi (429)2012 OpenAPI 3.1API līguma apraksts (mašīnlasāms)2021 OWASPAPI Security Top 10:20232023 SP 800-204Mikroservisu drošības stratēģijas (NIST)2019 ISO 27001ISMS - A.8 tehniskās kontroles2022

Saistība ar NIS2

Droša API izstrāde un testēšana atbilst NIS2 (ES 2022/2555) 21. panta 2. punkta e) apakšpunkta prasībām par drošību iegādē, izstrādē un uzturēšanā.

GDPR

Atbildē jāatklāj tikai nepieciešamais (datu minimizācija) - pārmērīga datu atklāšana (OWASP API3) ir arī personas datu aizsardzības pārkāpums.

Atruna

Materiāls ir izglītojošs pārskats, nevis standartu pilnais teksts. Konkrētai ieviešanai vienmēr jāskata oficiālais avots.