Open Data Protocol (OData) a Diplomaterv Portálon

Utolsó frissítés: 2011. június 30. – Utolsó verzió: V1

A Diplomaterv Portálon nyilvánosan megjelenő legfontosabb információk elérhetőek programozottan is a platform független, REST alapú Open Data Protocol (OData) segítségével, ezáltal lehetővé válik a szakdolgozatok és diplomatervek adatainak megjelenítése máshol (például tanszéki honlapokon) is.

Fontos, hogy a Portál OData API-jának nem célja az összes tárolt adat programozói interfészen keresztüli publikálása. A cél az, hogy a lényeges adatok máshol is felhasználhatóak legyenek és onnan a felhasználók eljuthassanak a Diplomaterv Portálra, ahol a jogosultságtól függően további információkat érhetnek el.

Aktuális verzió és URL-ek

A Diplomaterv Portál az OData protokoll V2 verzióját támogatja (lásd DataServiceVersion: 2.0 fejléc mező).

A Diplomaterv Portál által biztosított OData API aktuális verziószáma V1. Ez a verziószám független az OData protokoll verziójától, használata azért szükséges, hogy az adatmodell vagy az URL-ek jövőbeli esetleg változása ne legyen hatással az API-t addigra már használó kliens alkalmazások működésére.

A Diplomaterv Portál OData szolgáltatásának végpontja a http://diplomaterv.vik.bme.hu/OData/aktuális verzió/ címen található. Az aktuális verzió V1, ennek megfelelően a szolgáltatás gyökér URL-je: http://diplomaterv.vik.bme.hu/OData/V1/

Az URL-ekben az entitások és mezők nevei érzékenyek a kis- és nagybetűkre, azaz case sensitive-ek. A szolgáltatás gyökér URL-jének megadásánál nincs különbség a kis- és nagybetűk között, azaz case insensitive.

Az adatmodell

A Portál adatbázisából a témák (Thesis), a témákhoz tartozó kulcsszavak (Tag), az oktatók és hallgatók (User), valamint a tanszékek (Department) egyes tulajdonságai kérdezhetőek le. Az egyes entitások tulajdonságai és kapcsolataik az alábbi ábrán láthatóak:

Az adatmodell legfontosabb jellemzői:

Minden entitásnak van egy egyedi, állandó, numerikus ID tulajdonsága, ami elsődleges kulcsként funkcionál.
A PortalUrl tulajdonság egy olyan abszolút URL-t tartalmaz, ami a Diplomaterv Portálra mutat és ahol az adott entitással kapcsolatos összes adat megtalálható.

Az adatmodell teljes XML formátumú leírása lekérdezhető a http://diplomaterv.vik.bme.hu/OData/aktuális verzió/$metadata címen.

Bővítmények

A http://odata.org oldalon található protokoll dokumentációhoz képest a Diplomaterv Portál két további funkciót biztosít.

1. JSON formátum kérése URL-ben

Az alap OData protokoll szerint a szerver automatikusan JSON formátumú választ ad, ha a kliensről érkező kérés tartalmazza a Accept: application/json fejléc sort. Ezen túlmenően a Diplomaterv Portál lehetőséget ad JSON formátumú válasz kérésére az URL-ben megadott $format=json opció segítségével.

Például: http://diplomaterv.vik.bme.hu/OData/aktuális verzió/Theses(1)?$format=json

2. JSONP támogatás

Az alap JSON formátumon kívül a Portál a JSONP (JSON with padding) formátumot is támogatja a $callback (fontos, hogy $ jellel kezdődik) opció segítségével. Amennyiben a kérés tartalmazza a $callback opciót, akkor a válasz automatikusan JSON formátumú lesz.

Például: http://diplomaterv.vik.bme.hu/OData/aktuális verzió/Theses(1)?$callback=myCallbackFunction

Korlátozások

A Portál az OData protokollt az alábbi korlátozásokkal támogatja:

OData protokollon keresztül csak az adatok lekérdezése lehetséges, módosítása nem. Az adatok módosítására továbbra is csak a portálra bejelentkezve van lehetőség, programozói interfészen keresztül nem.
Minden entitásból egyidejűleg maximum 100 példány kérdezhető le. Amennyiben az adott entitásból több, mint 100 példány található, akkor az eredményhalmaz végén megjelenik egy link, amely a következő 100 elem lekérdezésére szolgáló URL-re mutat.
A szerver a válaszban beállítja az Expires fejléc mezőt, amely 5 percre engedélyezi a kliensnek a válasz gyorsítótárazását.

Példák

Álljon itt néhány példa a Diplomaterv Portál OData API-jának illusztrálására. Fontos, hogy a Portál a teljes Open Data Protocolt támogatja, tehát az itt bemutatottakon kívül sokkal több lehetőséget biztosít. Ezekről bővebben a protokoll dokumentációjában található leírás.

Gyakori URL-ek

Ebben a fejezetben a leggyakoribb lekérdezéskre mutatunk példát. Az egyszerűség kedvéért a példákban csak relatív útvonalak szerepelnek, amiket a szolgáltatás gyökér URL-jének kell megelőznie.

Egy tanszék összes témája lekérdezhető a tanszék rövidítése segítségével:
Theses?$filter=Supervisor/Department/Abbreviation eq 'tanszék rövidítése'
Például az Automatizálási és Alkalmazott Informatikai Tanszék (AAIT) esetén:
Theses?$filter=Supervisor/Department/Abbreviation eq 'AAIT'

Egy tanszék összes témája a témán dolgozó hallgató és a konzulens adataival együtt:
Theses?$filter=Supervisor/Department/Abbreviation eq 'tanszék rövidítése'&$expand=Supervisor,Student

Egy tanszék összes témája a témán dolgozó hallgató és a konzulens adataival együtt cím szerint rendezve:
Theses?$filter=Supervisor/Department/Abbreviation eq 'tanszék rövidítése'&$expand=Supervisor,Student&$orderby=TitleHu

Egy konzulens összes témája a konzulens neve szerint:
Theses?$filter=Supervisor/DisplayName eq 'konzulens teljes neve'

Egy konzulens összes témája a konzulens neve szerint JSON formátumban:
Theses?$filter=Supervisor/DisplayName eq 'konzulens teljes neve'&$format=json

Egy konzulens összes témája a konzulens neve szerint JSONP formátumban:
Theses?$filter=Supervisor/DisplayName eq 'konzulens teljes neve'&$callback=myCallback

Egy konzulens összes témája a konzulens neve szerint a hallgató adataival:
Theses?$filter=Supervisor/DisplayName eq 'konzulens teljes neve'&$expand=Student

Egy konzulens összes témája a konzulens neve szerint a hallgató adataival, de csak a cím és nevek:
Theses?$filter=Supervisor/DisplayName eq 'konzulens teljes neve'&$expand=Student&$select=TitleHu,Student/DisplayName

Az összes olyan téma, aminek a címében szerepel a "mobil" szó:
Theses?$filter=indexof(TitleHu,'mobil') gt 0

jQuery

Az OData protokollon keresztül lekérdezett adatok más honlapokon történő megjelenítésére a jQuery osztálykönyvtárt ajánljuk. Az alábbi példában a jQuery és a jQuery Templates plugin használatával egy tanszék összes témáját jelenítjük meg egy felsorolásos listában.

1. Helyezzünk el az oldal HTML kódjában egy ul elemet, ami a felsorolásos lista elemeit fogja tartalmazni:

  <ul id="itemParent"></ul>

2. Készítsünk az oldalra egy sablont, ami alapján a lista egyes elemeit fogjuk elkészíteni:

  <script id="itemTemplate" type="text/x-jquery-tmpl">
    <li>
      <a href="${PortalUrl}">${TitleHu}</a> 
      <em>(${Supervisor.DisplayName})</em>
    </li>
  </script>

3. Az oldal fejlécében hivatkozzunk a jQuery és a jQuery Templates plugin osztálykönyvtárakra:

  <script src="jquery-1.6.1.min.js" type="text/javascript"></script>
  <script src="jquery.tmpl.min.js" type="text/javascript"></script>

4. JSONP protokoll segítségével kérdezzük le az adatokat és a sablon alapján jelenítsük is meg őket az oldal betöltődésekor:

  <script type="text/javascript">
    $(function () {
      $.ajax({
        dataType: "jsonp",
        url: "http://diplomaterv.vik.bme.hu/OData/V1/Theses?$filter=Supervisor/Department/Abbreviation eq 'AAIT'&$expand=Supervisor",
        jsonp: '$callback',
        success: function (response, status, xhr) {
          $("#itemTemplate").tmpl(response.d.results).appendTo("#itemParent");
        }
      });
    });
  </script>

A példa teljes forráskódja és további példák letölthetőek innen:

DiplomatervPortalODataPeldak.zip

Visszajelzés

Amennyiben a Diplomaterv Portál OData API-jával kapcsolatban ötlete, véleménye, visszajelzése lenne, kérjük írja meg nekünk a
címre "Visszajelzés a Diplomaterv Portál OData API-jával kapcsolatban" tárgysorral. Köszönjük!