API - Application programming interface

API je kratica za Application Programming Interface. Pri spletnem razvoju izraz navadno pomeni programski vmesnik, s katerim spletna stran uporablja dodatne zmožnosti brskalnika ali spletne platforme. Tako lahko stran ne prikazuje le besedila in slik, ampak tudi shranjuje podatke, uporablja lokacijo, deluje brez povezave ali izvaja del kode v ozadju.

Sodobni spletni brskalniki vključujejo veliko vgrajenih API-jev. Med pogoste sodijo API za vlečenje elementov, geolokacijo, shranjevanje podatkov v brskalniku, delo brez povezave in izvajanje kode v ločeni niti.

Osnovna pravila

Pri uporabi spletnih API-jev je smiselno upoštevati nekaj osnovnih pravil:

• API-je praviloma uporabljamo prek JavaScripta.
• Nekateri API-ji zahtevajo uporabnikovo dovoljenje, na primer geolokacija.
• Nekatere funkcije delujejo le v varnem okolju, običajno prek protokola HTTPS.
• Podpora za posamezen API se lahko med brskalniki razlikuje, zato je priporočljivo preveriti, ali je API na voljo.

Primerjava nekaterih spletnih API-jev

Drag and Drop

API Drag and Drop omogoča, da elemente na strani povlečemo in spustimo na drugo mesto. Pri tem običajno uporabimo atribut draggable ter dogodke dragstart, dragover in drop. Za omogočeno spuščanje ciljni element praviloma potrebuje klic event.preventDefault() v dogodku dragover.

Osnovni postopek je tak:

• element označimo kot vlečljiv z atributom draggable="true",
• ob začetku vlečenja shranimo njegov id,
• na ciljnem elementu dovolimo spuščanje,
• ob dogodku drop element premaknemo v ciljno območje.

<script>
function allowDrop(ev) {
  ev.preventDefault();
}
function drag(ev) {
  ev.dataTransfer.setData("text", ev.target.id);
}
function drop(ev) {
  ev.preventDefault();
  var data = ev.dataTransfer.getData("text");
  ev.currentTarget.appendChild(document.getElementById(data));
}
</script>

<div class="dropbox" ondragover="allowDrop(event)" ondrop="drop(event)">
  <div id="predmet1" class="dragitem" draggable="true" ondragstart="drag(event)">HTML</div>
  <div id="predmet2" class="dragitem" draggable="true" ondragstart="drag(event)">CSS</div>
  <div id="predmet3" class="dragitem" draggable="true" ondragstart="drag(event)">JavaScript</div>
</div>

Geolocation

Geolocation API omogoča pridobivanje podatkov o uporabnikovi lokaciji. Brskalnik za uporabo praviloma zahteva dovoljenje uporabnika. Ta API deluje v varnem kontekstu, kar pomeni, da se običajno uporablja prek povezave HTTPS. Za pridobitev trenutne lokacije uporabimo metodo getCurrentPosition().

<p id="lokacija1">Pridobi podatke o geolokaciji:</p>
<button onclick="getLocation1()">Pokaži lokacijo</button>

<script>
var izpis1 = document.getElementById("lokacija1");

function getLocation1() {
  if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(pokaziLokacijo1, pokaziNapako1);
  } else {
    izpis1.innerHTML = "V tem brskalniku geolokacija ni podprta.";
  }
}

function pokaziLokacijo1(position) {
  izpis1.innerHTML = "Geografska širina: " + position.coords.latitude +
  "<br>Geografska dolžina: " + position.coords.longitude;
}

function pokaziNapako1() {
  izpis1.innerHTML = "Pridobivanje lokacije ni uspelo ali pa je bilo zavrnjeno.";
}
</script>

Web Storage

Web Storage API omogoča shranjevanje parov ključ–vrednost v brskalniku. Najpogosteje uporabljamo localStorage in sessionStorage. localStorage podatke ohrani tudi po zaprtju brskalnika, medtem ko sessionStorage podatke hrani le do konca seje oziroma zavihka. Obe možnosti sta sinhroni, zato nista namenjeni shranjevanju večjih količin podatkov.

Primer: localStorage

<p>To stran si obiskal <b id="stevecLocal"></b> krat.</p>
<button onclick="pocistiLocal()">Počisti localStorage</button>

<script>
if (!localStorage.getItem('pageCounterLocal')) {
  localStorage.setItem('pageCounterLocal', 0);
}
localStorage.setItem(
  'pageCounterLocal',
  parseInt(localStorage.getItem('pageCounterLocal')) + 1
);
document.getElementById('stevecLocal').innerHTML = localStorage.getItem('pageCounterLocal');

function pocistiLocal() {
  localStorage.removeItem('pageCounterLocal');
  location.reload();
}
</script>

Primer: sessionStorage

<p>To stran si obiskal v tem zavihku <b id="stevecSession"></b> krat.</p>
<button onclick="pocistiSession()">Počisti sessionStorage</button>

<script>
if (!sessionStorage.getItem('pageCounterSession')) {
  sessionStorage.setItem('pageCounterSession', 0);
}
sessionStorage.setItem(
  'pageCounterSession',
  parseInt(sessionStorage.getItem('pageCounterSession')) + 1
);
document.getElementById('stevecSession').innerHTML = sessionStorage.getItem('pageCounterSession');

function pocistiSession() {
  sessionStorage.removeItem('pageCounterSession');
  location.reload();
}
</script>

Delo brez povezave

Starejši primeri HTML5 pogosto omenjajo Application Cache oziroma datoteko manifest, vendar je ta pristop zastarel in se ne uporablja več. Za sodobno delo brez povezave uporabljamo predvsem Service Worker, ki lahko prestreza omrežne zahteve, uporablja predpomnilnik in omogoča učinkovitejše delovanje strani tudi brez povezave.

Web Workers

Web Workers omogočajo izvajanje JavaScripta v ozadju, ločeno od glavne niti strani. To je uporabno pri daljših ali zahtevnejših opravilih, saj lahko stran med tem ostane odzivna. Worker nima neposrednega dostopa do DOM-a, z glavno stranjo pa komunicira s sporočili.

<p>Štetje števil: <output id="rezultat"></output></p>
<button onclick="startWorker()">Zaženi Web Worker</button>
<button onclick="stopWorker()">Zaustavi Web Worker</button>

<script>
var w;

function startWorker() {
  if (typeof(Worker) !== "undefined") {
    if (typeof(w) === "undefined") {
      w = new Worker("demo_workers.js");
    }
    w.onmessage = function(event) {
      document.getElementById("rezultat").innerHTML = event.data;
    };
  } else {
    document.getElementById("rezultat").innerHTML =
      "Vaš brskalnik ne podpira Web Workers.";
  }
}

function stopWorker() {
  if (typeof(w) !== "undefined") {
    w.terminate();
    w = undefined;
  }
}
</script>

Priporočila

• Pred uporabo API-ja preverimo, ali ga brskalnik podpira.
• Pri geolokaciji uporabimo varen kontekst in uporabnika jasno obvestimo o namenu uporabe lokacije.
• Za manjše količine podatkov uporabimo localStorage ali sessionStorage, za zahtevnejše rešitve pa druge mehanizme.
• Za delo brez povezave uporabljamo sodobne pristope s Service Worker.
• Za dolgotrajnejša opravila v JavaScriptu uporabimo Web Workers, da stran ostane odzivna.

Pogoste napake

• Predpostavka, da vsi API-ji delujejo v vseh brskalnikih brez preverjanja podpore.
• Uporaba geolokacije brez upoštevanja dovoljenj in varnega konteksta.
• Napačno razumevanje razlike med localStorage in sessionStorage.
• Uporaba zastarelih rešitev za delo brez povezave.
• Pričakovanje, da bo Web Worker lahko neposredno spreminjal DOM.