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 and 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": "Општинска управа Врбас",
            "page": "https://data.gov.rs/organizations/opshtinska-uprava-vrbas/",
            "slug": "opshtinska-uprava-vrbas",
            "uri": "https://data.gov.rs/api/1/organizations/5ac373a6cbe3c80f19373daf/",
            "url": "http://www.vrbas.net/"
        }
    ],
    "next_page": "https://data.gov.rs/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": "10"
}

Ово је веома детаљно и још увек нам није неопходно да имамо све те информације. Зато користимо јq.

Потврда да јq функционише

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

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

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

"Општинска управа Врбас"

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

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

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

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

То је добар почетак, а сада хајде да истражимо сâм API. Иако то још увек не знамо, већ смо преузели нашу прву организацију.

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

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

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

"Општинска управа Врбас"
"Градска управа Града Ваљево"
"Градска управа града Шапца"
"Канцеларија за информационе технологије и електронску управу"
"Data Science Serbia"
"Град Нови Пазар - Градска управа за изворне и поверене послове"
"Институт за јавно здравље Србије - "Др Милан Јовановић Батут""
"Републички завод за статистику"
"Градска управа за саобраћај и путеве - Нови Сад"
"Градска управа Града Ниша "

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

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

"https://data.gov.rs/api/1/organizations/5ac373a6cbe3c80f19373daf/"
"https://data.gov.rs/api/1/organizations/5a9feb84cbe3c80f19373d4b/"
"https://data.gov.rs/api/1/organizations/5a8ff70ccbe3c80f19373cbc/"
"https://data.gov.rs/api/1/organizations/5a7957cecbe3c87b002bb529/"
"https://data.gov.rs/api/1/organizations/5891bbe9cbe3c81427571bb2/"

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

$ http $API'organizations/5ac373a6cbe3c80f19373daf/' | jq '.'

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

$ http $API'organizations/5ac373a6cbe3c80f19373daf/' | jq '.metrics'

{
 "datasets": 1,
 "followers": 1,
 "reuses": 0,
 "members": 3,
 "permitted_reuses": 0,
 "badges": 0,
 
}

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

$ http $API'organizations/5ac373a6cbe3c80f19373daf/' | jq '.members[].user.last_name'

"Ђорђевић"
"Косанић"
"Парезановић"

На вама је да преузмете податке који су од значаја за ваш пројекат. Не оклевајте да прођете кроз jq's tutorial and приручник ако желите да детаљно прегледате 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-ја или поставили питања у вези с њим!