• harremanetarako

• euskara
• español
• english

REST APIaren dokumentazioa

Hauek dira APIaren diseinu-helburu nagusiak:

• REST arkitektura estiloa erabili.

• Ezartzeko erraza den API garbi bat diseinatzea. Orain APIa Ruby on Rails plataforman ezarrita dago baina etorkizunean berrezarri edota bestelako plataformetara hedatu ahal izango da, adibidez, PHP edo Zope plataformetan.

• OpenLayers liburutegia erabili mapak erakutsi eta horiekin lan egiteko. Horri esker,Mapstraction-ekin guztiz bateragarriak izango gara.

• TMS Open Layers-i mapak zerbitzatzeko.

• Bestelako API estandarrei atxikitzen saiatu, horrek eskaintzen dituen elkarrekiko eraginkortasun abantailez gozatzeko.

• Etorkizunean, Open Geospatial Consortium (OGC) elkartearen zerbitzuak ezarri. Zerbitzu horien artean:

  • WMS

  • WMS-C

  • WFS

Oro har, APIa bi zatitan banatzen da:

• Kontsultak egiteko eta informazioa lortzeko APIa.
• Mapak txertatzeko eta horiekin lan egiteko APIa. Beste norbait garatzen ari den aplikazioan leiho bat txertatzeko.

Oharpen orokorrak

API hau HTTP bidez eskuragarri dago eta REST estiloari jarraitzen dio. Diseinuari dagokionez, APIari berdin zaio egingo den inplementazioa nolakoa den, nahiz eta Ruby on Rails-en REST inplementazioaren diseinuaren xehetasun txiki batzuk izan. Ruby on Rails-en eragina kasuan kasu zehaztuta dago.

Koordenatu motak

Kontrakoa adierazten ez bada, API honetan erabiltzen diren koordenatu guztiak (luzera/latitudea) Spherical Mercator proiekzioan aurki daitezke eta "EPSG:900913" SRS-a daukate.

APIaren oinarrizko URL-a

Dokumentu honetan agertzen diren URL guztiak APIaren zerbitzariaren oinarrizko URL-ean aplikatzen dira. Hau da oraingo oinarrizko URL-a:

b5m.gipuzkoa.eus/api/

Azpimarratu behar da Ruby On Rails-eri berdin zaiola zein den erabilitako domeinua, izan ere, web aplikazioa eskatzen den URL-aren domeinura berez egokitzen baita.

Bertsionatua

APIa bertsionatuta dago. Horri esker, egun APIa erabiltzen duten bezeroei arazorik eragin gabe garapenean aurrera jarraitu dezake. Bertsioa adierazten duten zenbakiek honako forma daukate:

handiago.txikiago

Dokumentu honetan APIaren 1.0 bertsioa deskribatzen da. Hortaz, hau izango da oinarrizko URL-a:

b5m.gipuzkoa.eus/api/1.0/

APIaren bertsio bat denboran iraunkor mantentzen saiatu behar da erabiltzen duten bezeroei arazoak ez sortzeko.

Lokalizazioa

Kontsulta askoren erantzunak bezeroak bilatu nahi duen testua jaso behar du.

Bilaketaren hautaketa RESTful moduan egiten da, hau da, URL-aren path-ean hizkuntza kode bat sartuz. Hori, querystring-ak (adibidez, "?lang=es") ez erabiltzeko egiten da, RestBible-k gomendatzen duenari jarraiki (121-123 or.).

Hizkuntza kodeak ISO 639-1 estandarrari jarraiki zehazten dira. Hauek dira gure aplikazioan erabiliko ditugun kode nagusiak:

 - Euskara:    eu
 - Gaztelania: es
 - Ingelesa:     en
 - Frantsesa:    fr

Hizkuntza kodea APIaren bertsio-zenbakiaren ondoren zehazten da, adibidez:

/api/1.0/eu/

URL-en path-aren (direktorioen katea) REST “egitura” ingelesez dago eta independentea da hautatutako lokalizazioarekiko. Izan ere, ez baitauka zentzurik URL-ak hautatutako lokalizazioaren arabera aldatzea. REST estiloa dela-eta, path-aren zati batzuk kontsultaren parametroekin bat etor daitezke eta hortaz, lokalizatu daitezke.

Horrela, entitateak (herriak, kaleak, etab.) bilatzeko erabiltzen diren “kodeak” kontsultako parametroetan lokalizatuta daude.

Adibidez, objektu baten MBRa lortzeko (informazio gehiago APIaren xehetasunetan)

/api/1.0/eu/locate/mbr/M_069

Lehen adierazi dugun bezala, locale-a URL-aren bitartez hautatzen da. Momentuz, ez zaio jaramonik egiten HTTP Accept-Language goiburuari. Horrek bat egiten du REST (RestBible 93,391) estiloarekin.

Edonola ere, APIk itzultzen duen testu-eduki osoa UTF-8 formatuan kodetuta dago. Momentuz, ez diogu jaramonik egingo HTTP Accept-Charset goiburuari (RestBible 390).

EPSG

APIak baimentzen du emaitzak jasotzea erreferentzia-sistema hauetan: EPSG:900913an (Spherical Mercator, balio lehenetsia), EPSG:4326an (WGS84) eta EPSG:25830ean (ETRS89). Erreferentzia-sistemaren aukeraketa, srs parametroaren bidez egiten da.

/api/1.0/eu/locate/mbr/M_069.xml;srs=epsg:25830
/api/1.0/eu/locate/mbr/M_069.xml;srs=epsg:4326
/api/1.0/eu/locate/mbr/M_069.xml;srs=epsg:900913

Irteera formatua

APIak hainbat modutan adierazten ditu baliabideak (datuak).

• JSON
• XML
• TEXT (TXT,CSV)

Formatua aukeratzeko ondoren ematen den zerrendatik betetzen den lehen baldintza hautatzen da (Rails estiloa):

1. Eskaeraren URL-ari “formatu luzapen” bat gehituz. Adibidez:

   /api/1.0/eu/locate/mbr/M_069.xml
   /api/1.0/eu/locate/mbr/M_069.json
   

2. HTTP Content goiburua erabiliz egokiena den MIME type-arekin.

3. Aipatutako bi baldintzak betetzen ez badira, XML formatua lehenetsiko da.

Baliabide guztiak ez daude formatu guztietan eskuragarri. Oro har, baliabideekin batera horiek zein formatu bitartez lor daitezkeen zehazten duen zerrenda bat atxikitzen da. Formatuen zerrenda eskuratzeko nahikoa da “.formats” luzapena gehitzea “baliabide mota” ezartzen duen URL-ari. Adibidez:

• /api/1.0/eu/locate/mbr.formats
  /api/1.0/eu/locate/info.formats
  

Horrela, baliabide horrek onartzen dituen formatuak jasotzen dituen testu CSV bat lortzen da.

JSONP formatua

APIak datuak JSONP formatuan itzul ditzake. Hori lortzeko, callback-aren funtzioa zein den zehaztu behar da.

Callback-a zehazteko URL-aren querystring bat erabili ohi da. Gure kasuan:

/api/1.0/eu/locate/mbr/M_069.jsonp?callback=nire_funtzioa

Callback-a zehazteko modu honek ez du REST-en arkitektura estiloa mantentzen eta ez da cache friendly. Horregatik, callback-a zehazteko REST-etik hurbilago dagoen modu bat aukeratu da.

Callback-a zehazteko URL-aren parametro bat (eta ez querystring bat) erabili ohi da:

/api/1.0/eu/locate/mbr/M_069.jsonp;callback=nire_funtzioa

Callback parametroa URL-kodetuta egon daiteke. Nahiz eta oso ohikoa ez den, callback-ean "." erabiltzen bada, hori URL-kodetu beharko da. Izan ere, karaktere guztiak URL-kodeaketa gomendatzen da (letrak eta digituak ez ezik):

/api/1.0/eu/locate/mbr/M_069.jsonp;callback=form%5B0%5D%2Efuncion   # honakoaren baliokidea da: "form[0].funcion"

Eskaera adibideak:

Eskaera:

/api/1.0/eu/locate/info/D_4545.json

Emaitza:

{
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
}

Eskaera:

/api/1.0/eu/locate/info/D_4545.jsonp;callback=funcion

Emaitza:

funcion({
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
})

Eskaera:

/api/1.0/eu/locate/info/D_4545.jsonp;callback=form%5B0%5D%2Efuncion

Emaitza:

form[0].funcion({
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
})

APIren antolaketa hierarkikoa (''namespaces-eak'' edota izenen guneak)

APIaren URL-ak hierarkikoki egituratuta daude. Lehenik eta behin, zein baliabidetara sartu behar den zehazten da identifikatzaile baten bidez.

Ondoren, URL-ak gainontzeko baliabideak hierarkikoki identifikatuko ditu, horiek “handitik txikira” sailkatuz.

Aldaketak egiteko REST eragiketak

APIaren egungo bertsioak HTTP-ren GET metodoa onartzen du soilik, hau da, datuak eskuratu daitezke soilik. APIak ez ditu PUT, POST eta DELETE metodoak onartzen.

Segurtasuna eta erabileraren kontrola

APIaren egungo bertsioak ez du erabiltzailea egiaztatzeko sistemarik onartzen (API key) Sarbide guztiak anonimoak dira eta ez daude mugatuta.

URL-en egituraren laburpena

APIaren definizioa

Definizio hauetako URL-ak bat datoz dagozkion URL-aren aurrezenbakiarekin.

"configuration/" namespace-a

URL horiek konfigurazio datuak itzultzen dituzte.

Namespace configuration adibideen orrialdea.

"locate/" namespace-a

URL guztiek datuak itzuli eta objektuak aipatzen dituzte.

Hauek dira baimenduta dauden Objektuak:

Search/-en egindako bilaketaren emaitzaren formatua:

Namespace locate adibideen orrialdea.

"query/" namespace-a

URL horiei esker, koordenatu baten inguruan dauden objektuei buruzko informazioa lor daiteke.

(*) Koordenatu bat eta bilatu nahi diren objektu geografiko moten zerrenda bat emanez gero, koordenada horrek hartzen duen azaleran dauden objektu geografikoen zerrenda eskaintzen du ("puntu horretan dauden objektuak"). Zehaztutako objektu geografikoak soilik egiaztatzen dira, beraz, ez da inoiz eskainiko zehaztu gabeko objektu geografikorik. Parametroak:

lat: latitudea
lon: luzera
tolerance: puntu jakin bat emanik, bere inguruan eremu bat definitzen duen erradioa Km-tan, bertan bilaketa egin ahal izateko (balioa 0 izango da puntuan bertan bilatzeko).
codes: Kakotxen ("T,D,E") edo izartxoen bidez ("*") banandutako objektu geografikoen zerrenda eskuragarri dauden kode guztiak egiaztatzeko. 

"layer/" namespace-a

URL hauek geruza bati (ortoargazkia, mapa edota pictometry) dagokion informazioa eskaintzen dute.

Namespace layer adibideen orrialdea.

"pictometry/" Namespace-a

URL hauek pictometry irudiei buruzko informazioa erakusten dute,

"Namespace pictometry adibideen orrialdea".

"library/" Namespace-a

URL hauei esker, bezeroak Javascript liburutegiak kargatu ditzake. Oinarrizko liburutegia “openlayers” bada ere, adibide (eta produktu) guztietan “prototype” eta “scriptaculous” erabiliko dira. Horregatik, momentuz, liburutegi horiek ere bezeroei irekita egongo dira.

Ibilbidea errazteko liburutegiaren izenarekin osatutako aurrizki bat erabiliko dugu, izan ere, openlayers/-en barruan OpenLayers-ek behar dituen baliabideak (img/, css/...) gordetzen dituzten direktorio “ezkutuan” baitaude.

Bezeroek liburutegiak bestelako guneetatik ere karga ditzakete.

Namespace library adibideen orrialdea.

"osgeo/" namespace-a

URL hauek OSGEO definitutako “estandarretara” sartzeko erabiltzen dira. Momentuz, TMS-etara sartzeko soilik erabiltzen dira.

Eskuragarri dauden kartografiak:

Namespace osgeo adibideen orrialdea.

Aplikazioaren adibidea

API honek eskaintzen dituen aplikazioetako bat ikus daiteke adibide honetan.