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 |
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:
- 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
- ha nincs bejelentkezve, a bajelentkezés oldalra kerül, majd sikeres bejelentkezés után: lásd előző pont
- 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
