API kūrimas pradedantiesiems

Kas yra API ir kodėl verta suprasti šią sąvoką

Jei kada nors naudojai orų programėlę telefone, mokėjai internetu ar prisijungei prie svetainės per „Google” paskyrą – tu jau naudojai API. Tik galbūt to nežinojai. API (Application Programming Interface) – tai tarsi sutartas bendravimo protokolas tarp dviejų programų. Viena programa klausia, kita atsako. Viskas.

Bet čia ir prasideda painiava. Daugelis pradedančiųjų programuotojų girdi žodį „API” ir galvoja, kad tai kažkas labai sudėtingo, skirto tik patyrusiems inžinieriams. Iš tikrųjų API kūrimas yra vienas iš tų dalykų, kurį galima išmokti gana greitai – jei tik supranti pagrindinę logiką.

Paprasčiausias pavyzdys: tu rašai programą, kuri nori gauti informaciją apie tam tikrą miestą – temperatūrą, drėgmę, vėjo greitį. Tu neparašysi savo meteorologinės stoties. Vietoj to, tu kreipsiesi į kokio nors oro tarnybos API, siųsi užklausą su miesto pavadinimu, ir gausi atsakymą su visais reikalingais duomenimis. Tavo programa ir oro tarnybos serveris „susikalbėjo” per API.

Šiame straipsnyje kalbėsime apie tai, kaip pačiam sukurti tokį komunikacijos kanalą – nuo nulio, be baimės ir be nereikalingo sudėtingumo.

REST API – de facto standartas, kurį verta mokėti

Yra keletas API tipų: SOAP, GraphQL, gRPC ir kiti. Bet jei esi pradedantysis, pradėk nuo REST (Representational State Transfer). Kodėl? Nes tai šiuo metu populiariausias ir plačiausiai naudojamas API stilius internete. Beveik kiekviena šiuolaikinė paslauga – „Twitter”, „Spotify”, „GitHub” – turi REST API.

REST API veikia per HTTP protokolą, kurį jau naudoja internetas. Tai reiškia, kad nereikia mokytis kažkokio specialaus protokolo – pakanka suprasti, kaip veikia interneto užklausos. REST API naudoja kelis pagrindinius HTTP metodus:

• GET – gauti duomenis (pvz., gauti vartotojo informaciją)
• POST – sukurti naują įrašą (pvz., registruoti naują vartotoją)
• PUT arba PATCH – atnaujinti esamą įrašą
• DELETE – ištrinti įrašą

Šie metodai kartu su URL adresais sudaro tai, ką vadiname „endpoint” arba galutiniu tašku. Pavyzdžiui, GET /users/42 reiškia „duok man vartotojo su ID 42 duomenis”. DELETE /users/42 reiškia „ištrink tą vartotoją”. Logika paprasta ir intuityvi.

Svarbus REST principas – „statelessness”, arba būsenos nebuvimas. Kiekviena užklausa turi savyje visą reikalingą informaciją. Serveris nesaugo informacijos apie tai, ką tu darei prieš tai. Tai gali atrodyti keistai iš pradžių, bet iš tikrųjų tai labai patogi architektūra – serveris tampa paprastesnis ir lengviau išplečiamas.

Pasirink įrankius: su kuo pradėti

Teorija – gerai, bet praktika – geriau. Prieš rašant pirmą eilutę kodo, reikia apsispręsti, kokią technologiją naudosi. Čia nėra vieno teisingo atsakymo, bet yra keletas populiarių pasirinkimų pradedantiesiems:

Node.js su Express – turbūt populiariausias pasirinkimas pradedantiesiems, kurie jau šiek tiek moka JavaScript. Express yra minimalus ir lankstus framework’as, kuris leidžia sukurti veikiantį API per kelias eilutes kodo. Bendruomenė milžiniška, dokumentacija puiki, pavyzdžių internete – begalė.

Python su FastAPI arba Flask – jei moki Python, tai natūralus pasirinkimas. Flask yra paprastas ir lengvai suprantamas, FastAPI – šiek tiek sudėtingesnis, bet turi automatinį dokumentacijos generavimą ir yra greitesnis. Abiem atvejais Python sintaksė leidžia rašyti labai skaitomą kodą.

Django REST Framework – jei nori „baterijos įskaičiuotos” sprendimo su daug funkcijų iš karto, tai geras pasirinkimas. Bet pradedantiesiems gali būti per daug abstrakcijų iš karto.

Šiame straipsnyje naudosime Node.js su Express kaip pavyzdį, nes JavaScript žino daugelis, o Express logika yra labai aiški. Bet principai, kuriuos aprašysime, taikomi bet kuriai technologijai.

Prieš pradedant, įsitikink, kad turi įdiegtą Node.js. Patikrink terminale:

node --version
npm --version

Jei matai versijų numerius – viskas gerai. Jei ne – eik į nodejs.org ir parsisiųsk.

Pirmasis API: nuo tuščio failo iki veikiančio serverio

Sukurk naują katalogą, atidaryk terminalą ir inicializuok projektą:

mkdir mano-api
cd mano-api
npm init -y
npm install express

Dabar sukurk failą index.js ir įrašyk šį kodą:

const express = require('express');
const app = express();
const PORT = 3000;

app.use(express.json());

// Pavyzdinis duomenų masyvas
let vartotojai = [
  { id: 1, vardas: 'Jonas', el_pastas: '[email protected]' },
  { id: 2, vardas: 'Ona', el_pastas: '[email protected]' }
];

// GET - gauti visus vartotojus
app.get('/vartotojai', (req, res) => {
  res.json(vartotojai);
});

// GET - gauti vieną vartotoją pagal ID
app.get('/vartotojai/:id', (req, res) => {
  const vartotojas = vartotojai.find(v => v.id === parseInt(req.params.id));
  if (!vartotojas) {
    return res.status(404).json({ klaida: 'Vartotojas nerastas' });
  }
  res.json(vartotojas);
});

// POST - sukurti naują vartotoją
app.post('/vartotojai', (req, res) => {
  const naujas = {
    id: vartotojai.length + 1,
    vardas: req.body.vardas,
    el_pastas: req.body.el_pastas
  };
  vartotojai.push(naujas);
  res.status(201).json(naujas);
});

// DELETE - ištrinti vartotoją
app.delete('/vartotojai/:id', (req, res) => {
  const indeksas = vartotojai.findIndex(v => v.id === parseInt(req.params.id));
  if (indeksas === -1) {
    return res.status(404).json({ klaida: 'Vartotojas nerastas' });
  }
  vartotojai.splice(indeksas, 1);
  res.status(204).send();
});

app.listen(PORT, () => {
  console.log(`Serveris veikia: http://localhost:${PORT}`);
});

Paleisk serverį: node index.js. Jei matai pranešimą apie veikiantį serverį – sveikiname, tu ką tik sukūrei savo pirmąjį API.

Dabar gali testuoti naudodamas naršyklę (tik GET užklausoms) arba įrankį kaip Postman ar Insomnia – tai grafines sąsajas turintys įrankiai, leidžiantys siųsti visų tipų HTTP užklausas. Labai rekomenduojama juos įsidiegti – jie taps nuolatiniu tavo darbo įrankiu.

HTTP statuso kodai – kalba, kurią turi mokėti

Pastebėjai, kad kode naudojome res.status(404) ir res.status(201)? Tai HTTP statuso kodai – ir jie yra labai svarbi API komunikacijos dalis. Klientas, gavęs atsakymą, pirmiausia žiūri į statuso kodą, kad suprastų, ar viskas gerai.

Pagrindinės grupės:

• 2xx – sėkmė. 200 OK (viskas gerai), 201 Created (resursas sukurtas), 204 No Content (sėkmingai įvykdyta, bet nėra ką grąžinti).
• 4xx – kliento klaida. 400 Bad Request (bloga užklausa), 401 Unauthorized (reikia prisijungti), 403 Forbidden (neturi teisių), 404 Not Found (resursas nerastas).
• 5xx – serverio klaida. 500 Internal Server Error (kažkas nutiko serveryje), 503 Service Unavailable (servisas nepasiekiamas).

Dažna pradedančiųjų klaida – visada grąžinti 200, net kai įvyko klaida. Tai labai apsunkina klaidų tvarkymą kliento pusėje. Jei vartotojas nerastas – grąžink 404. Jei duomenys blogi – grąžink 400. Jei kažkas sugedo serveryje – grąžink 500. Tai ne formalumas, tai komunikacijos protokolo dalis.

Kitas svarbus dalykas – atsakymų formatas. Šiuo metu standartinis formatas yra JSON (JavaScript Object Notation). Jis lengvai skaitomas žmonių, lengvai apdorojamas mašinų. Visada grąžink struktūruotą JSON, net kai grąžini klaidą:

{
  "klaida": "Vartotojas su šiuo ID nerastas",
  "kodas": 404
}

Tai leidžia klientui programiškai apdoroti klaidas, o ne tiesiog rodyti neaiškų tekstą.

Autentifikacija ir saugumas – tai ne prabanga

Vienas iš dažniausių klausimų: „Kaip apsaugoti API?” Ir tai labai teisingas klausimas, nes atvirą API gali naudoti bet kas – ir ne visada geranoriškai.

Pradedantiesiems rekomenduojama pradėti nuo JWT (JSON Web Tokens). Principas paprastas: vartotojas prisijungia su slaptažodžiu, serveris grąžina tokeną (ilgą šifruotą eilutę), ir vėliau kiekviena užklausa siunčia šį tokeną antraštėje. Serveris patikrina tokeną ir žino, kas siunčia užklausą.

Įdiek biblioteką: npm install jsonwebtoken bcryptjs

Paprastas prisijungimo endpoint’as atrodytų taip:

const jwt = require('jsonwebtoken');
const bcrypt = require('bcryptjs');

const SLAPTAS_RAKTAS = 'labai-slaptas-raktas-niekam-nerodyti';

app.post('/prisijungti', async (req, res) => {
  const { el_pastas, slaptazodis } = req.body;
  
  // Rask vartotoją duomenų bazėje
  const vartotojas = vartotojai.find(v => v.el_pastas === el_pastas);
  if (!vartotojas) {
    return res.status(401).json({ klaida: 'Neteisingi duomenys' });
  }
  
  // Patikrink slaptažodį
  const teisingas = await bcrypt.compare(slaptazodis, vartotojas.slaptazodis);
  if (!teisingas) {
    return res.status(401).json({ klaida: 'Neteisingi duomenys' });
  }
  
  // Sukurk tokeną
  const tokenas = jwt.sign(
    { id: vartotojas.id, el_pastas: vartotojas.el_pastas },
    SLAPTAS_RAKTAS,
    { expiresIn: '24h' }
  );
  
  res.json({ tokenas });
});

Keletas svarbių saugumo patarimų, kurių neturėtum ignoruoti:

• Niekada nesaugok slaptažodžių tekstiniu pavidalu. Visada naudok bcrypt arba panašią biblioteką.
• Slapti raktai turi būti aplinkos kintamuosiuose, ne kode. Naudok .env failus ir biblioteką dotenv.
• Naudok HTTPS produkcijoje. HTTP siunčia duomenis nešifruotai.
• Ribok užklausų skaičių (rate limiting). Biblioteka express-rate-limit padės apsisaugoti nuo brute force atakų.
• Validuok įvesties duomenis. Niekada nepasitikėk tuo, ką siunčia klientas. Biblioteką joi arba express-validator labai rekomenduojama naudoti.

Dokumentacija – tavo API vizitinė kortelė

Galbūt tai skamba nuobodžiai, bet gera dokumentacija yra tai, kas skiria profesionalų API nuo mėgėjiško. Jei tu kuri API, kurį naudos kiti žmonės (ar net tu pats po kelių mėnesių), dokumentacija yra būtina.

Geras standartas – OpenAPI (anksčiau vadintas Swagger). Tai specifikacija, leidžianti aprašyti visus API endpoint’us, parametrus, atsakymų formatus. Ir svarbiausia – iš šios specifikacijos automatiškai generuojama interaktyvi dokumentacija, kurioje galima tiesiogiai testuoti užklausas.

Su Express gali naudoti biblioteką swagger-ui-express kartu su swagger-jsdoc. Tai leidžia rašyti dokumentaciją tiesiai kode kaip komentarus:

/**
 * @swagger
 * /vartotojai:
 *   get:
 *     summary: Gauti visus vartotojus
 *     responses:
 *       200:
 *         description: Vartotojų sąrašas
 */
app.get('/vartotojai', (req, res) => {
  res.json(vartotojai);
});

Jei nori dar paprastesnio sprendimo – FastAPI (Python) generuoja dokumentaciją automatiškai, be jokių papildomų pastangų. Tai viena iš priežasčių, kodėl daugelis renkasi šį framework’ą.

Net jei nenaudoji automatinių įrankių, bent jau sukurk paprastą README.md failą su:

• Visų endpoint’ų sąrašu
• Kiekvieno endpoint’o parametrais ir atsakymų pavyzdžiais
• Autentifikacijos instrukcijomis
• Klaidų kodų aprašymais

Nuo kodo iki veikiančio produkto – ir ko dar reikia žinoti

API kūrimas – tai ne tik kodas. Tai ir mąstymas apie tai, kaip jis bus naudojamas, kaip jis augs, kaip bus prižiūrimas. Pradedantieji dažnai sustoja ties „veikia mano kompiuteryje” etapu, bet realus API turi veikti serveryje, būti pasiekiamas iš interneto ir atlaikyti apkrovą.

Keletas dalykų, kuriuos verta žinoti tolimesniam keliui:

Duomenų bazė. Šiame straipsnyje naudojome masyvą atmintyje – tai tinka mokymosi tikslams, bet ne realiam naudojimui. Išmok naudoti bent vieną duomenų bazę. PostgreSQL yra puikus pasirinkimas – patikimas, galingas, nemokamas. MongoDB – jei patogiau dirbti su JSON formato duomenimis. Kartu su Node.js dažnai naudojamas Prisma arba Sequelize kaip ORM (Object-Relational Mapping) sluoksnis.

Versijų valdymas. Kai API keičiasi, reikia užtikrinti, kad seni klientai vis dar veiktų. Standartinė praktika – versijuoti URL: /api/v1/vartotojai, /api/v2/vartotojai. Taip gali keisti naują versiją nesulaužydamas senų integracijų.

Testavimas. Rašyk testus savo API. Jest su Supertest (Node.js) arba pytest (Python) leidžia automatiškai patikrinti, ar visi endpoint’ai veikia teisingai. Tai ypač svarbu, kai API auga ir keičiasi – testai užtikrina, kad nieko nesulaužei.

Diegimas. Populiarūs pasirinkimai pradedantiesiems: Railway, Render arba Heroku (nors pastarasis tapo mokamas). Visi jie leidžia labai paprastai įdiegti Node.js arba Python aplikacijas. Ateityje verta išmokti Docker ir debesų platformas kaip AWS ar Google Cloud.

Stebėjimas. Kai API veikia produkcijoje, reikia žinoti, kas vyksta. Naudok logging bibliotekas (pvz., Winston Node.js aplinkoje), stebėk klaidas (Sentry yra puikus ir turi nemokamą planą), sekk našumą.

API kūrimas iš pradžių gali atrodyti kaip didelis kalnas, bet iš tikrųjų tai labai logiškas ir nuoseklus procesas. Pradėk nuo paprasčiausio veikiančio pavyzdžio, suprask HTTP metodus ir statuso kodus, išmok autentifikaciją, pridėk duomenų bazę – ir štai, tu jau turi solidų pagrindą. Kiekvienas profesionalus backend’o kūrėjas pradėjo lygiai taip pat: nuo Hello World iki pirmo veikiančio serverio, nuo pirmo veikiančio serverio iki pirmo realaus projekto. Svarbiausia – nesustoti ties teorija ir pradėti rašyti kodą. Net jei jis netobulas. Ypač jei jis netobulas.