Neticle Wiki

Megmutatjuk mit gondol a Web!

Felhasználói eszközök

Eszközök a webhelyen


api

Neticle API

Figyelem! Az API specifikáció még nem végleges!

Absztrakt

A Neticle API hozzáférést biztosít a Neticle rendszer által feldolgozott adatokhoz külső programok és / vagy szolgáltatások számára. Az API HTTP alapokon működik és a REST elvet követi.

API kapcsolat

Ahhoz, hogy az API-val kapcsolatot tudjon létesíteni, a kliens szoftverben telepíteni kell a Neticle CA tanusítványt. Ez a tanusítvány a http://ca.neticle.hu/ oldalról tölthető le. A kliens szoftvernek a Neticle CA által kiállított webszerver tanusítványokat hitelesnek kell elfogadnia.

Ezen felül minden kérő programnak rendelkeznie kell egy API azonosítóval és egy titkos kulccsal amiket minden API kéréshez HTTP Basic autentikáció (RFC2617 2. szekció) formájában át kell küldeni a Neticle szervernek.

A Neticle API bázis URL-je: https://api.neticle.hu/0.1/

Minden API hívás a bázis URL alatt helyezkedik el. A bázis URL tartalmaz egy verziószámot ami az API hívások verzióját határozza meg. A Neticle API minden API verziót legalább a megjelenését követő 1 évig támogat. Az API verziók követése érdekében feliratkozhat az API levelezési listára.

Adatformátumok

A Neticle API több féle adatformátumon is képes kommunikálni. A jelenleg támogatott adatformátumok a következők:

  • JSON (application/json)

Az adatformátumokat két féle képpen lehet átadni a Neticle API-nak:

  • Az fmt=formátumnév paraméterrel a címsorban
  • Az Accept fejléc használatával.

A kérés és a válasz formátumának mindig meg kell egyeznie!

API hívások

A lekérdezés URL-ek felépítése

Minden lekérdezés URL a következő formában épül fel:

bázis URL/client/ügyfélazonosító/profile/profilazonosító/keyword/kulcsszó/erőforrás

illetve a profilra lekérdezhető adatokra:

bázis URL/client/ügyfélazonosító/profile/profilazonosító/erőforrás

Ezt követik ? után az esetleges finomító paraméterek, mint például a dátumszűkítés.

Ügyfélazonosítók lekérdezése

Azokat az ügyfélazonosítókat adja vissza, amelyhez az adott API kulccsal hozzáférése van. A lekérdezés a következő:

GET /0.1/client/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs es jelszo kodolva RFC2617 2. szekció szerint
Accept: application/json

A válasz a következő képpen néz ki:

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":1,"name":"Teszt Ugyfel 1"},{"id":2,"name":"Teszt Ugyfel 2"}]

Az alkalmazás a saját hatáskörében fix konfigurációként is kezelheti az ügyfél azonosítókat mivel ezek nem változnak.

Profilazonosítók lekérdezése

Egy ügyfélen belül azokat a profilokat adja vissza, amihez az adott API kulccsal hozzáférése van.

GET /0.1/client/1/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs es jelszo kodolva RFC2617 2. szekció szerint
Accept: application/json

A válasz a következő képpen néz ki:

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":1,"name":"Teszt Profil 1"},{"id":2,"name":"Teszt Profil 2"}]

Az alkalmazás a saját hatáskörében fix konfigurációként is kezelheti a profil azonosítókat mivel ezek nem változnak, azonban érdemes az alkalmazást több profil fogadására is alkalmassá tenni.

Kulcsszavak lekérdezése

Ez a lekérdezés az ügyfélen és profilon belül érvényes és a kulcsszavak listáját adja vissza.

GET /0.1/client/1/profile/2/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs es jelszo kodolva RFC2617 2. szekció szerint
Accept: application/json

A válasz a következő:

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":1,"name":"keyword1"},{"id":2,"name":"keyword2"}]

A kulcsszóazonnosítók adott esetben változhatnak, az alkalmazás ezeket ne kezelje statikusan!

WOI lekérdezése

A WOI (véleményárfolyam) egy-egy kulcsszóra vagy profilra kérdezhető le agregáltan, így a következő lekérdezések érvényesek:

GET /0.1/client/1/profile/2/woi HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs es jelszo kodolva RFC2617 2. szekció szerint
Accept: application/json

illetve

GET /0.1/client/1/profile/2/keyword/3/woi HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs es jelszo kodolva RFC2617 2. szekció szerint
Accept: application/json

A címhez hozzáfűzhető dátumszűkítés is:

GET /0.1/client/1/profile/2/woi?fromDate=2013-03-23&untilDate=2013-04-23 HTTP/1.1

A fromDate és untilDate maximum 60 napos időszakot határozhat meg. A lekérdezésben mindkét dátum benne lesz a válasz tartományban. Amennyiben ezek a paraméterek nincsenek megadva, a rendszer automatikusan az utolsó 30 nap WOI értékeit adja vissza.

A dátum minden esetben a katonai formátum szerint írandó: ÉÉÉÉ-HH-NN

A WOI válasz így néz ki:

HTTP/1.1 200 OK
Content-Type: application/json

[{"date":"2013-03-23","value":1.27},...]

Említésfolyam lekérdezése

Napi gyakoriság lekérdezése

Elemzett szövegek lekérdezése

Legtöbbet említő oldalak lekérdezése

Legtöbbet említő szerzők lekérdezése

Hibajelzések

A Neticle API lekérdezés hibára néhány kivételtől eltekintve a HTTP/1.1 400 Bad Request válasszal válaszol. A válasz törzse minden esetben tartalmazza a hiba okát és lehetséges javítási javaslatokat HTML formátumban angol nyelven.

Túl gyakori lekérdezések

Amennyiben az adott API kulcs túllépte a megengedett lekérdezési keretet (API kulcsonként egyéni), a rendszer HTTP/1.1 429 Too Many Requests válasszal válaszol (RFC6585) és a Retry-After fejlécben megadja a másodpercek számát amit a kliensnek még várakoznia kell. Ez esetben a kliens kötelessége ezt megjegyezni és addig nem próbálkozni, amíg ez az idő le nem jár.

Fontos! Az Retry-After fejlécben megfogalmazott időkorlát be nem tartása a rendszer védelme érdekében az API kulcs automatikus zárolásával jár és csak emberi erővel oldható fel, ami jelentős (1-2 napos) kiesést jelenthet az API elérhetőségében.

api.txt · Utolsó módosítás: 2013/12/03 11:36 szerkesztette: eszter