SocialApiSpec

A iWiW Fejlesztői Wiki wikiből

Az "iWiW Social API" az iWiW Devportálon regisztrált OpenSocial gadgetek számára nyújtott szolgáltatások összessége. A következő szabványok egy részét  valósítja meg:

Fontos! Ha nincs OpenSocial gadgeted az iWiW-en, és nem is tervezel fejleszteni, akkor számodra az iWiW Connect API a megoldás.

Tartalomjegyzék

API főkapcsoló

Azok a felhasználók, akik nem engedélyezték az alkalmazások használatát (beállítások oldal, "Részt akarok venni az alkalmazások funkcióban"), semmilyen módon nem érhetőek el az API-n keresztül (azaz pl. nem kérhetőek le people service-el, nem lehetnek notification címzettjei, stb.) Számukra a gadgetek sem jelennek meg a felületen.

Az alkalmazások által generált activityket a felhasználók a főkapcsoló állásától függetlenül megkapják.

Hogyan érhető el a Social API?

Az API két módon érhető el:

  • A felhasználók böngészőjében futó OpenSocial gadgetekből JavaScript API-n keresztül
  • Ha a gadgetnek van "backend" szervere, számára a REST API érhető el

Az alább említett korlátozások és limitek mind a JavaScript, mind a REST api esetén összevonva érvényesek.

Fontos! A Social API szolgáltatások és korlátozások köre megegyezik a gadgetek felé a JavaScript API és a gadgetek backendje felé REST API esetében, egy fontos kivétellel: az "activities" szolgáltatás nem érhető el gadgetek számára REST API-n keresztül.

REST API

Végpontok:

Támogatott adatformátumok:

  • JSON, XML.
  • POST és PUT HTTP kérések "Content-Type" fejlécét egyeztetni kell a kérés tartalmával (body), azaz:
    • JSON esetén a következők egyike: application/json, text/x-json, application/javascript, application/x-javascript, text/javascript, text/ecmascript, application/json-rpc, application/jsonrequest
    • XML esetén: text/xml, application/xml
    • Fontos! Az application/x-www-form-urlencoded típus nem támogatott.

Autentikáció

Az iWiW Social API REST interfészen keresztül való eléréséhez OAuth protokollon keresztül szükséges autentikálni. Ennek működése OAuth 1.0 és OAuth 1.0a szabvány szerinti.

A szolgáltatások elérése kétlábas OAuth autentikáción keresztül lehetséges, melynek feltétele, hogy az alkalmazás az adott (xoauth_requestor_id paraméter által meghatározott) felhasználónak telepítve legyen, ellenkező esetben az OAuth hibaválasz oauth_problem paraméterének értéke permission_denied lesz.

Az OpenSocial gadgetek autentikációját a böngésző és az iWiW Social API között a rendszer transzparens módon elvégzi, azzal a fejlesztőknek nem kell foglalkozni.

Szolgáltatások

People

Olvasnivalók

Támogatott REST kérések

HTTP method: GET

URI struktúrák:

  • /people/{guid}/{groupid}
    • guid: tetszőleges Person azonosítója vagy @me
    • groupid: csak @self vagy @friends lehet (utóbbi csak @me esetén)
  • /people/@me
  • /people/@me/@friends
  • /people/{guid}

Megkötések

Gadgetek JavaScript API-n keresztül a következő felhasználói adatokhoz férhetnek hozzá:

  • tulajdonos (OWNER) profil adatai
  • tulajdonos ismerőseinek (OWNER FRIENDS) profil adatai
  • néző (VIEWER) profil adatai
  • néző ismerőseinek (VIEWER FRIENDS) profil adatai
  • tetszőleges felhasználó profil adatai, ha ismert az azonosítója

A felhasználó azonosítója nem egyezik meg az iWiW-en használt számmal, hanem a "domain:azonosító" formátumú, például "sandbox.iwiw.hu:29W017W90m". Az előtagot képező rész "sandbox.iwiw.hu" és "iwiw.hu" értékeket vehet fel, a második rész pedig egy változó hosszú, de maximum 16 karakterből álló betű-szám halmaz.

Támogatott mezők

  • id
  • name (familyName, givenName, formatted)
  • displayName
  • thumbnailUrl (profilképe 64x64 pixelesre átméretezve)
  • profileUrl
  • hasApp
  • nickname
  • gender
  • currentLocation (country, locality)
  • utcOffset
  • languagesSpoken

Default REST mezők

  • id
  • name
  • thumbnailUrl
  • isOwner
  • isViewer
  • hasApp
  • profileUrl

Default JS API mezők

  • id
  • name
  • thumbnailUrl
  • displayName
  • isOwner
  • isViewer
  • hasApp
  • profileUrl

Paraméterek

  • fields
  • sortOrder
    • ascending (default)
    • descending
    • random
  • filter
    • id
    • hasApp
  • filterOptions
    • filterOp : startsWith | contains | equals
        • contains -> csak Collection-okre és name-re használható
        • startsWith -> PersonName-re, tombokre, es primitiv tipusokra is
    • filterBy -> a mező neve. pl.: name
    • filterValue -> a keresett érték
  • count (default 20)
  • networkDistance (max 1)
  • startIndex

Activities

Fontos! Az activities szolgáltatás jelenleg kizárólag activity létrehozást támogat (lekérdezést, listázást nem).

Olvasnivalók:

Támogatott REST kérések

HTTP method: POST

URI struktúrák:

  • /activities/{guid}/{groupid}
    • guid csak @me vagy @viewer lehet
    • groupid csak @self
  • /activities/@me/@self
  • /activities (az előzővel egyenértékű)

Megkötések

  • Activity csak VIEWER számára hozható létre és csak abban az esetben, ha azt alkalmazás felvételekor engedélyezte.
  • A megfelelő felhasználó és az engedélyezés ellenőrzése szinkron módon történik, tiltás esetén HTTP 403 (forbidden) a válasz.

Támogatott mezők

  • body (max 970 karakter) *
  • title (max 220 karakter) *
  • templateParams *
  • bodyId
  • titleId
  • mediaItems (max 1 db.)
    • url (500) 
    • thumbnailUrl (500) 
    • title (200) 
    • description (500) 
    • type (üres és 'image') 
  • (mimeType-ot jelenleg figyelmen kivul hagyja a rendszer) 

Tartalmi megkötések

A *-al jelölt mezőknek:

  • valid XML fragmentnek kell lennie
  • támogatott HTML tagek: "a", "b", "i", "u", "br"
  • támogatott entytik: "amp", "gt", "lt", "quot"
  • "a" tagen támogatott a href attribútum

MediaItem megkötések

  • Egy activityhez csak egy MediaItem adható meg.
  • Groupolt activityknél nem jelenik meg a MediaItem title és description. 
  • Az url és thumbnailUrl minden esetben proxysítva lesz. 
  • A mediaItemek megjelenítése értelemszerűen nem befolyásolható (nem templatesíthető). 
  • A MediaItem title-ben és descriptionben nem támogatott semmilyen html formázás. 
  • Legalább a thumbnailUrl megadása kötelező. 
  • A thumbnailUrl-nek kép (image/jpeg, image/png, vagy image/gif) típusú tartalomra kell mutatnia.

Bármilyen tartalmi megkötés megsértése HTTP 400 (bad request) válaszkódot eredményez.

Limitek

  • Egy alkalmazás egy felhasználó számára 24 órán belül 5 Activity-t hozhat létre, túllépése HTTP 417 (expectation failed) hibaválaszt eredményez. (Ez a limit a sandboxon a tesztelést megkönnyítendő 100 db 24 órán belül.)

Példák

Activity létrehozása: 

POST http://api.sandbox.iwiw.hu/social/connect/rest/activities
Content-Type: application/json

{
 "title": "Hello",
 "body": "world!" 
}

Appdata

Az alkalmazások jellemzően futásuk során információkat, adatokat tárolnak el a felhasználók tevékenysége kapcsán. Az OpenSocial API, és az iWiW megvalósítása erre lehetőséget kínál, vagyis nem feltétlenül kell külső szerverhez folyamodnunk ha adatokat szeretnénk letárolni.

Olvasnivalók:

Támogatott REST kérések

HTTP methodok: GET, POST, DELETE

URI struktúrák

  • /appdata/{guid}/{groupid}
  • GET /appdata/@me/{groupid}
    • guid: @me (@viewer, @owner)
    • groupId: @self, @friends
  • POST /appdata/@me (guid csak @me lehet)
  • TODO

TODO: fields

Korlátozások

  • 10 kulcs-érték pár (mindkettő string), melynek túllépése esetén HTTP 417 (expectation failed) a válasz
  • a kulcs értéke legfeljebb 500 byte
  • Az alkalmazás az éppen aktuális felhasználó (VIEWER, @viewer/@self vagy @me/@self) adatait tudja csak írni, és bármely más felhasználóét melyekhez hozzáfér (tulajdonos és tulajdonos ismerősei, néző és néző ismerősei) korlátlanul olvasni. Kiemelten figyeljünk rá, hogy érzékeny információt az adatok ilyen jellegű publikussága miatt nem szabad letárolnunk!

Messages

Fontos! A messages szolgáltatás jelenleg kizárólag notification típusú üzenet létrehozását támogatja (lekérdezést, listázást, más típusokat nem).

Olvasnivalók

Támogatott REST kérések

HTTP method: POST

URI struktúrák:

  • /messages/{guid}/{msgcollid}
    • guid: csak @me lehet
    • msgcollid: csak @outbox lehet
  • /messages/@me/@outbox

Korlátozások

A felhasználók szabályozhatják, hogy egy alkalmazás tudjon-e számukra értesítést küldeni, illetve hogy hogyan kapják meg az értesítéseket, s az őket nem érdeklődő vagy zavaró alkalmazások értesítéseit le is tudják tiltani. Lehetséges állapotok:

  • Kérek értesítéseket webes felületen és emailben is.
  • Csak webes felületen kérek értesítést.
  • Letiltja az alkalmazás összes értesítését a jövőben.

A blokkolt alkalmazások egy külön oldalon külön listázhatóak.

A tiltás aszinkron módon van ellenőrizve, azaz az alkalmazás nem tudja válaszkódban "érzékelni", hogy az adott értesítés kézbesítése sikerült-e.

Támogatott mezők

  • type: kötelezően "notification"
  • body (max 4000 karakter) (?)
  • recipients: kötelezően egy eleme van: az értesítés címzettje

Limitek

  • egy alkalmazás percenként legfejlebb 1000 értesítést küldhet
  • egy alkalmazás naponta (azaz az adott naptári napon) és 1000 felhasználónként 1000000 értesítést küldhet
  • a limitek szinkron módon vannak ellenőrizve
  • a limitek túllépése esetén HTTP error 417 kódú válasz keletkezik

Példák

"Hello!" üzenet küldése "sandbox.iwiw.hu:m9VGWkh2" azonosítójú felhasználónak: 

POST http://api.sandbox.iwiw.hu/social/connect/rest/messages/@me/@outbox
Content-Type: application/json

{
 "body": "Hello!", 
 "recipients": ["sandbox.iwiw.hu:m9VGWkh2"], 
 "type": "notification"
}
A lap eredeti címe: „http://dev.iwiw.hu/wiki/index.php/SocialApiSpec”
Személyes eszközök