API dokumentacija

Za programere i razvoj aplikacija

Na ovoj stranici nalazi se opis rada besplatnog i otvorenog RESTful API-ja ovog veb-sajta

Potrvrda identiteta

Da biste mogli da izvršite operacije pisanja, prvo morate da potvrdite identitet i dobijete API ključ u postavkama profila.

Taj klјuč treba da bude obezbeđen za svaki poziv u X-API-KEY HTTP zaglavlju.

Autorizacije

Za API pozive potrebne su iste dozvole kao za veb-interfejs.

Na primer, morate biti član neke organizacije da biste promenili neki od skupova podataka te organizacije.

Numerisanje stranica

Neke metode imaju numeraciju stranica i uvek prate isti obrazac. Lista objekata je uvijena u objekat Page.

Ne morate sami da izračunavate prethodne i naredne stranice jer su URL-ovi dostupni kao odgovor u okviru atributa previous_page i next_page. Biće postavlјeni na vrednost null ako ne postoji prethodna i/ili naredna stranica.

Primer: 


{
    "data": [{...}, {...}],
    "page": 1,
    "page_size": 20,
    "total": 10,
    "next_page": "https://data.gov.rs/api/endpoint/?page=2",
    "previous_page": null
}

Primeri

Svi primeri koriste httpie i jq uslužne programe zbog čitlјivosti. Međutim, te alatke ne morate da koristite u svom kodu; one vam samo pomažu da bolјe razumete API.

Provera da li httpie funkcioniše

Kad se httpie instalira, možete proveriti da li funkcioniše tako što ćete otkucati komandu u terminalu:

$ http 'https://data.gov.rs/api/1/organizations/?page_size=1'

Rezultat bi trebalo da bude nešto slično ovome:


HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
... LOTS OF HEADERS ...

{
    "data": [
        {

            ... LOTS OF DATA ...

            "name": "Sigurne Staze",
            "page": "https://data.gov.rs/organizations/sigurne-staze/",
            "slug": "sigurne-staze",
            "uri": "https://data.gov.rs/api/1/organizations/60d0de8b7de272ad982965c3/",
            "url": "https://sigurnestaze.com/"
        }
    ],
    "next_page": "https://data.gov.rs/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": "10"
}

Potvrda da jq funkcioniše

Kad se jq instalira, možete proveriti da li funkcioniše tako što ćete otkucati komandu u terminalu:

$ http 'https://data.gov.rs/api/1/organizations/?page_size=1' | jq '.data[].name'

Rezultat bi trebalo da bude nešto slično ovome:

"Sigurne Staze"

To je već bolјe! Sada kad smo sigurni da funkcioniše kao što je očekivano, hajde da malo skratimo komandnu liniju:

$ export API="https://data.gov.rs/api/1/"

Претходна команда је сада еквивалентна следећој читљивијој команди (не заборавите наводнике):

$ http $API'organizations/?page_size=1' | jq '.data[].name'

Pregled i preuzimanje podataka

Možete preuzeti listu organizacija (filtriranu ili nefiltriranu) ili jednu organizaciju. Kad stignete do krajnje tačke, podrazumevana veličina stranice iznosi 20. Hajde da preuzmemo prvih 20 organizacija iz API-ja:

$ http $API'organizations/' | jq '.data[].name'

"Sigurne Staze"
"Општина Велика Плана"
"Републички завод за статистику #2021"
"Форум младих са инвалидитетом Крагујевац"
"Општина Лајковац"
"Centar za odrzivi razvoj ,,MARKRIKAT""
"Фондација Каталист"
"Centar za razvoj neformalnog obrazovanja građana"
"Општина Ковачица"
"Општина Врбас

Ova lista je sjajna, ali šta ako želimo da prođemo kroz listu vraćenih organizacija? Hajde da preuzmemo URI-je prvih 5 organizacija:

$ http $API'organizations/?page_size=5' | jq '.data[].uri'

"https://data.gov.rs/api/1/organizations/60d0de8b7de272ad982965c3/"
"https://data.gov.rs/api/1/organizations/60c9e81f7de272a90fc17ca8/"
"https://data.gov.rs/api/1/organizations/607f2e917de2727637f02829/"
"https://data.gov.rs/api/1/organizations/604e1d477de272ae4266de56/"
"https://data.gov.rs/api/1/organizations/5fbfab3d7de272d322b934f4/"

Sada možemo da preuzmemo jedinstvenu organizaciju zahvalјujući vraćenom URI-ju:

$ http $API'organizations/60d0de8b7de272ad982965c3/' | jq '.'

To je mnogo podataka za izračunavanje. Hajde da preradimo te podatke ako želimo isklјučivo metriku:

$ http $API'organizations/60d0de8b7de272ad982965c3/' | jq '.metrics'

{
    "datasets": 4,
    "members": 1,
    "views": 0,
    "followers": 0,
    "reuses": 4,
    "dataset_views": 0,
    "reuse_views": 0,
    "resource_downloads": 0,
    
}

Ili možda samo imena članova organizacije:

$ http $API'organizations/60d0de8b7de272ad982965c3/' | jq '.members[].user.last_name'
"Velić"

Na vama je da preuzmete podatke koji su od značaja za vaš projekat. Ne oklevajte da prođete kroz jq tutorijal i priručnik ako želite da detalјno pregledate API preko komandne linije.

Izmene i brisanje podataka

Upozorenje, ovo može da bude opasno! Izmene ili brisanja podataka pomoću API-ja ne mogu se opozvati i mi ne pružamo nikakav sandbox u kojem biste mogli to da testirate pre izvršenja (za sada). Pre upotrebe svojih privilegija, budite svesni svoje odgovornosti.

Ukoliko pokušate da izmenite resurs bez tokena za potvrdu identiteta, biće vraćen kôd 401:

$ http PUT $API'organizations/organization-uri-x/'

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Unauthorized",
    "status": 401
}

Morate da navedete API klјuč (pogledajte iznad) i da koristite X-API-KEY HTTP zaglavlјe. Ako pokušajte da izmenite resurs koji ne kontrolišete, biće vraćen kôd 400:

$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Invalid API Key",
    "status": 401
}

Ovo je poruka koju ćete dobiti ukoliko ste naveli pogrešan API klјuč. Postoji još jedna potencijalna poruka o grešci na koju možete da naiđete:


HTTP/1.1 403 FORBIDDEN
... LOTS OF HEADERS ...

{
    "message": "You do not have the permission to modify that object.",
    "status": 403
}

Pojavlјuje se ukoliko pokušate da pristupite resursu koji ne možete da menjate sa svojim akreditivima. Ukoliko je vaš klјuč validan, trebalo bi da dobijete nešto nalik sledećem:


HTTP/1.1 200 OK
... LOTS OF HEADERS ...

{
    ...
}

Međutim, ništa se nije promenilo! To je sasvim u redu, jer smo zaboravili da navedemo prave podatke koji će biti poslati na server.

$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here name="Lorem ipsum" description="The quick brown fox jumps over the lazy dog." | jq '{name: .name, description: .description}'

{
    "name": "Lorem ipsum",
    "description": "The quick brown fox jumps over the lazy dog."
}

Resurs je modifikovan sa želјenim vrednostima. Konačno, možete obrisati resurs upotrebom odgovarajućeg HTTP glagola (pazite, trenutno nije moguće opozvati operaciju brisanja kroz API):

$ http DELETE $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here

HTTP/1.0 204 NO CONTENT
... LOTS OF HEADERS ...

Kad to obavite, možete proveriti da li je promena stupila na snagu koristeći GET u odnosu na prethodni URI:

$ http GET $API'organizations/organization-uri-x/'

HTTP/1.0 410 GONE
... LOTS OF HEADERS ...

{
    "message": "Organization has been deleted",
    "status": 410
}

Konsultujte referentnu dokumentaciju u nastavku da biste pronašli više detalјa o upotrebi API-ja ili postavili pitanja u vezi s njim!

Referenca