ConnectApiSpec

A iWiW Fejlesztői Wiki wikiből

Az iWiW Connect API az OpenSocial RESTful 0.9 szabvány egy részét valósítja meg, és nagymértékben az iWiW Social API -n alapul, így ez a dokumentum csak az attól való eltéréseket tárgyalja.

Fontos! Ha van OpenSocial gadgeted az iWiW-en, vagy ilyet tervezel fejleszteni, ez az oldal nagy valószínűséggel nem neked szól. Lásd az iWiW Social API és az iWiW Gadgets specifikációkat.

Tartalomjegyzék 1 Hogyan érhető el a Connect API? 1.1 REST API végpontok 1.2 Korlátozások 1.3 Autentikáció 1.3.1 OAuth végpontok 1.3.2 Tokenek élettartama 1.3.3 Az accessToken válasz OAuth paraméterei 1.3.4 Egyéb korlátozások 2 Login az iWiW-vel 3 Névtelen felhasználó 4 Szolgáltatások 5 Javaslatok a felhaszáláshoz 6 Példák

Hogyan érhető el a Connect API?

A gadgetek esetében megszokotthoz hasonlóan a felhasználói azonosítókhoz "personId" formában lehet hozzáférni. Ez egy iWiW-es userId-re nem visszafordítható azonosítót jelent, ami azonos a Social és a Connect API esetében (azaz ugyanazon felhasználó esetében mindkét API-n keresztül ugyanazt a personId-t kapjuk).

REST API végpontok

• éles: http://api.iwiw.hu/social/connect/rest
• sandbox: http://api.sandbox.iwiw.hu/social/connect/rest

Korlátozások

A iWiW Social API lekérésekre érvényes limitek itt is érvényesek, továbbá:

• maximum 5000 felhasználó alkalmazásonként (azaz ennyi kiosztható access token)
  • túllépés esetén új access vagy request token létrehozásakor (accessToken vagy requesttoken hívás) a HTTP válasz oauth_problem paraméterének értéke consumer_key_rejected, státuszkódja 503
• alapesetben egy alkalmazás 1 órán belül legfeljebb 5000 kérést indíthat
  • Túllépése esetén a REST HTTP kérések 400-as státuszkódú választ adnak.

A fenti kvótákat az adminisztrátorok egyedi elbírálás alapján bővíthatik.

Autentikáció

A szolgáltatások elérése "háromlábas" OAuth autentikáción keresztül lehetséges, OAuth 1.0 és OAuth 1.0a szabvány szerint. (Ha nem tudod, mi az az OAuth, eszik-e vagy isszák, hasznos olvasmány lehet a Beginner’s Guide to OAuth.)

OAuth végpontok

• éles:
  • requestToken: http://api.iwiw.hu/social/oauth/requestToken
  • accessToken: http://api.iwiw.hu/social/oauth/accessToken
  • authorize: http://iwiw.hu/pages/auth/authorize.jsp
• sandbox:
  • requestToken: http://api.sandbox.iwiw.hu/social/oauth/requestToken
  • accessToken: http://api.sandbox.iwiw.hu/social/oauth/accessToken
  • authorize: http://sandbox.iwiw.hu/pages/auth/authorize.jsp

Tokenek élettartama

• request: 5 perc
• access: 1 év

Az accessToken válasz OAuth paraméterei

(A szabványos paramétereken felül.)

• user_id: a felhasználó Person azonosítója
• screen_name: a felhasználó Person displayName-je (ha nem anonim)
• anonymous=true: ha a felhasználó anonim

Egyéb korlátozások

• A requestToken callback_url paramétere max 255 karakter hosszú lehet
• Az authorize nem fogad el callback_url paramétert, "nem signolt" callback_url csak a devportálon adható meg. ("Dinamikus" callback URL-ek használatához javasoljuk az OAuth 1.0a szabvány szerint megvalósított "signed callback" használatát.)
• Mindhárom végponton csak a GET kérések támogatottak.
• Támogatott signature method-ok:  HMAC-SHA1, RSA-SHA1 (publikus kulcs PEM formátumban)

Login az iWiW-vel

Ha egy Site regisztrációjakor kiválasztották a "bejelentkezés az iWiW-vel" opciót, az oauth/authorize szolgáltatás működése a következőképp módosul:

1. ha a felhasználó be van jelentkezve és már korábban jóváhagyta az adott Site hozzáférését, a kérés automatikusan át lsz irányítva a callback_url-re
2. ha nincs bejelentkezve, a bajelentkezés oldalra kerül, majd sikeres bejelentkezés után: lásd előző pont
3. A visszaadott access token garantáltan azonos  a már korábban kiadottal.

A gyakorlatban ez azt jelenti, hogy ha már korábban belépett az adott site-ra az iWiW-vel, és adott pillanatban be van jelentkezve az iWiW-re, külön interakció nélkül beléptethető (leszámítva a "belépek az iWiW-vel" gombra kattintást).

A funkcionalitás névtelen felhasználó esetén is elérhető.

Névtelen felhasználó

Névtelen felhasználóval csak a people service érhető el, kizárólag az aktuális felhasználható kérdezhető le, és annak is csak a névtelen azonosítója (id) illetve a névtelenség mivoltát jelző flag (anonymous).

A névtelen azonosító iWiW szinten egyedi, azaz:

• egy azonosító csak egy felhasználónak osztható ki
• ugyanaz a felhasználó mindig ugyanazt a névtelen azonosítót kapja
• ugyanaz az azonosító nem osztható ki névtelen és nem-névtelen azonosítóként (azaz nem "keverednek")

A people-től különböző service felé irányuló kérések HTTP 403 (forbidden) választ adnak névtelen felhasználó esetén.

Szolgáltatások

Az iWiW Social API-n alapulnak, itt csak az eltéréseket tárgyaljuk:

• people: 
  • Csak azok a felhasználók érhetőek el, amelyek az adott alkalmazás hozzáférését engedélyezték (azaz pl. az ismerősök közül is csak azok!).
  • Névtelenül csatlakozott felhasználóról semmilyen személyes adat nem kérhető le, kivéve az anonim azonosítója, és az anonimitást jelző flag (anonymous=true). A névtelen felhasználók nem jelennek meg ismerős listában sem.
• activities: 
  • Ellentétben a Social API-val, a REST szolgáltatás itt elérhető.
  • Csak akkor használható, ha engedélyezte a felhasználó az adott alkalmazásnak az activity küldést.
  • Az engedélyezés ellenőrzése szinkron módon történik, tiltás esetén HTTP 403 (forbidden) a válasz.
• messages
  • Csak akkor használható, ha a címzett felhasználó engedélyezte az adott alkalmazás hozzáférését (aszinkron módon ellenőrizve).

Javaslatok a felhaszáláshoz

A jóváhagyó (authorize.jsp) oldalt önálló ablakban, olvasható url sávval kell megjeleníteni. Lásd ezt a threadet: http://groups.google.com/group/oauth/browse_thread/thread/c1e785f312fab9a8?pli=1

Példák

Példákódokat és útmutatókat itt találsz.