API документација

За програмере и развој апликација

На овој страници налази се опис рада бесплатног и отвореног RESTful API-ја овог веб-сајта

Потврда идентитета

Да бисте могли да извршите операције писања, прво морате да потврдите идентитет и добијете API кључ у поставкама профила.

Тај кључ треба да буде обезбеђен за сваки позив у X-API-KEY HTTP заглављу.

Ауторизације

За API позиве потребне су исте дозволе као за веб-интерфејс.

На пример, морате бити члан неке организације да бисте променили неки од скупова података те организације.

Нумерисање страница

Неке методе имају нумерацију страница и увек прате исти образац. Листа објеката је увијена у објекат Page.

Не морате сами да израчунавате претходне и наредне странице јер су URL-ови доступни као одговор у оквиру атрибута previous_page и next_page. Биће постављени на вредност null ако не постоји претходна и/или наредна страница.

Пример: 


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

Примери

Сви примери користе httpie и jq услужне програме због читљивости. Међутим, те алатке не морате да користите у свом коду; оне вам само помажу да боље разумете API.

Провера да ли httpie функционише

Кад се httpie инсталира, можете проверити да ли функционише тако што ћете откуцати команду у терминалу:

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

Резултат би требало да буде нешто слично овоме:


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"
}

Потврда да ли jq функционише

Кад се jq инсталира, можете проверити да ли функционише тако што ћете откуцати команду у терминалу:

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

Резултат би требало да буде нешто слично овоме:

"Sigurne Staze"

То је већ боље! Сада кад смо сигурни да функционише као што је очекивано, хајде да мало скратимо командну линију:

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

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

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

Преглед и преузимање података

Можете преузети листу организација (филтрирану или нефилтрирану) или једну организацију. Кад стигнете до крајње тачке, подразумевана величина странице износи 20. Хајде да преузмемо првих 20 организација из API-ја:

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

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

Ова листа је сјајна, али шта ако желимо да прођемо кроз листу враћених организација? Хајде да преузмемо URI-је првих 5 организација:

$ 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/"

Сада можемо да преузмемо јединствену организацију захваљујући враћеном URI-ју:

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

То је много података за израчунавање. Хајде да прерадимо те податке ако желимо искључиво метрику:

$ 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,
    
}

Или можда само имена чланова организације:

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

На вама је да преузмете податке који су од значаја за ваш пројекат. Не оклевајте да прођете кроз jq туторијал и приручник ако желите да детаљно прегледате API преко командне линије.

Измене и брисање података

Упозорење, ово може да буде опасно! Измене или брисања података помоћу API-ја не могу се опозвати и ми не пружамо никакав sandbox у којем бисте могли то да тестирате пре извршења (за сада). Пре употребе својих привилегија, будите свесни своје одговорности.

Уколико покушате да измените ресурс без токена за потврду идентитета, биће враћен кôд 401:

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

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

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

Морате да наведете API кључ (погледајте изнад) и да користите X-API-KEY HTTP заглавље. Ако покушајте да измените ресурс који не контролишете, биће враћен кôд 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
}

Ово је порука коју ћете добити уколико сте навели погрешан API кључ. Постоји још једна потенцијална порука о грешци на коју можете да наиђете:


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

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

Појављује се уколико покушате да приступите ресурсу који не можете да мењате са својим акредитивима. Уколико је ваш кључ валидан, требало би да добијете нешто налик следећем:


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

{
    ...
}

Међутим, ништа се није променило! То је сасвим у реду, јер смо заборавили да наведемо праве податке који ће бити послати на сервер.

$ 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."
}

Ресурс је модификован са жељеним вредностима. Коначно, можете обрисати ресурс употребом одговарајућег HTTP глагола (пазите, тренутно није могуће опозвати операцију брисања кроз API):

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

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

Кад то обавите, можете проверити да ли је промена ступила на снагу користећи GET у односу на претходни URI:

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

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

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

Консултујте референтну документацију у наставку да бисте пронашли више детаља о употреби API-ја или поставили питања у вези с њим!

Референца