API REST¶

Aquest document exposa els serveis web públics creats pel motor d’activitat i subscripcions. Aquests estan organitzats per recursos i les operacions sobre ells. Tots els serveis web són de tipus RESTful i l’intercanvi d’informació es realitza en format JSON.

Els paràmetres indicats a les seccions Query parameters, poden ser de 3 tipus:

REST:	Són obligatoris ja que formen part de la URI
Requerits:	Són obligatoris, però formen part de l’estructura JSON que s’envia amb el cos de la petició. En el cas de peticions GET, aquesta estructura equival a paràmetres de la URL. (i.e. ?context=ab0012313...)
Opcionals:	Com el nom indica, no son obligatoris, indiquen alguna funcionalitat extra

Tots els serveis requereixen autenticació oAuth en cas de que no s’especifiqui el contrari.

Les respostes que retorna el sistema, en cas que siguin 1 o múltiples resultats (Associats a col.leccions o entitats) seràn, o bé un sol objecte JSON en cas de l’accés a una entitat concreta, o una llista o array de resultats:

[
   { ... },
   { ... }
]

Usuaris¶

Operacions sobre el recurs usuari del sistema.

GET /people¶

Retorna el resultat d’una cerca d’usuaris del sistema en forma de llista de noms d’usuaris per l’ús de la UI.

Paràmetres JSON

username: El filtre de cerca d’usuaris.

Exemple de petició:

{"username": "messi"}

Resposta esperada:

[
    {
        "username": "messi",
        "displayName": "messi",
        "id": "519b00000000000000000000",
        "objectType": "person"
    }
]

Codis d’error:

200 petició executada correctament

Success

Retorna la llista d’usuaris que compleix la query especificada.

PUT /people/{username}¶

Modifica un usuari del sistema pel seu posterior us si existeix. En cas de que l’usuari no existeixi retorna un error. La llista de paràmetres actualitzables de moment es limita a displayName i a twitterUsername.

Query Parameters:
	username – (REST) L’identificador de l’usuari displayName – (Opcional) El nom real de l’usuari al sistema twitterUsername – (Opcional) El nom d’usuari de Twitter de l’usuari

Exemple de petició

{"displayName": "Lionel Messi", "twitterUsername": "messi10oficial"}

Resposta esperada:

{
    "username": "messi",
    "iosDevices": [],
    "displayName": "Lionel Messi",
    "talkingIn": [],
    "creator": "test_manager",
    "androidDevices": [],
    "following": [],
    "subscribedTo": [],
    "last_login": "2000-01-01T00:01:00Z",
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "twitterUsername": "messi10oficial",
    "id": "519b00000000000000000000",
    "objectType": "person"
}

Success

Retorna un objecte Person amb els paràmetres indicats modificats.

Error

{"error_description": "Unknown user: messi", "error": "UnknownUserError"}

POST /people/{username}¶

Crea el perfil propi (el de l’usuari que executa) d’usuari remotament al sistema pel seu posterior ús si no existeix. En cas de que l’usuari ja existis, el retorna canviant el codi d’estat HTTP en funció de l’acció realitzada.

Query Parameters:
	username – (REST) L’identificador del nou usuari al sistema displayName – (Opcional) El nom real (de pantalla) de l’usuari al sistema

Cos de la petició

{"username": "neymar", "displayName": "Neymar JR"}

Resposta esperada

{
    "username": "neymar",
    "iosDevices": [],
    "displayName": "Neymar JR",
    "talkingIn": [],
    "creator": "neymar",
    "androidDevices": [],
    "following": [],
    "subscribedTo": [],
    "last_login": "2000-01-01T00:01:00Z",
    "published": "2000-01-01T00:01:00Z",
    "owner": "neymar",
    "id": "519b00000000000000000000",
    "objectType": "person"
}

Success

Retorna un objecte Person.

GET /people/{username}¶

Retorna la informació d’un usuari del sistema. En cas de que l’usuari no existeixi retorna l’error especificat.

Query Parameters:
	username – (REST) L’identificador de l’usuari

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

{
    "username": "messi",
    "iosDevices": [],
    "displayName": "Lionel Messi",
    "talkingIn": [],
    "creator": "test_manager",
    "androidDevices": [],
    "following": [],
    "subscribedTo": [],
    "last_login": "2000-01-01T00:01:00Z",
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "twitterUsername": "messi10oficial",
    "id": "519b00000000000000000000",
    "objectType": "person"
}

Success

Retorna un objecte Person.

Error

{"error_description": "Unknown user: messi", "error": "UnknownUserError"}

GET /people/{username}/avatar¶

Retorna l’avatar (foto) de l’usuari del sistema. Aquest és un servei públic.

Query Parameters:
	username – (REST) L’identificador de l’usuari

Success: Retorna la imatge pel seu ús immediat.

POST /people/{username}/avatar¶

Permet a l’usuari del sistema pujar la seva imatge del seu perfil (avatar).

Query Parameters:
	username – (REST) L’identificador de l’usuari

Cos de la petició

La petició ha d’estar feta mitjançant multipart/form-data amb les capçaleres corresponents d’oAuth en aquest endpoint.

Success: Retorna un codi 201 (Created)

POST /people/{username}/device/{platform}/{token}¶

Afegeix un token de dispositiu al perfil de l’usuari. Aquest token és el que identifica el dispositiu per a que se li puguin enviar notificacions push.

Query Parameters:
	username – (REST) L’identificador del nou usuari al sistema platform – (REST) El tipus de plataforma token – (REST) La cadena de text que representa el token

Cos de la petició

Aquesta petició no necessita cos.

Resposta esperada

{
    "username": "messi",
    "iosDevices": [
        "12345678901234567890123456789012"
    ],
    "displayName": "Lionel Messi",
    "talkingIn": [],
    "creator": "test_manager",
    "androidDevices": [],
    "following": [],
    "subscribedTo": [],
    "last_login": "2000-01-01T00:01:00Z",
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "twitterUsername": "messi10oficial",
    "id": "519b00000000000000000000",
    "objectType": "person"
}

Success

Retorna un objecte Person.

DELETE /people/{username}/device/{platform}/{token}¶

Esborra un token de dispositiu al perfil de l’usuari. Aquest token és el que identifica el dispositiu per a que se li puguin enviar notificacions push.

Query Parameters:
	username – (REST) L’identificador del nou usuari al sistema platform – (REST) El tipus de plataforma token – (REST) La cadena de text que representa el token

Cos de la petició

Aquesta petició no necessita cos.

Resposta esperada

Retorna un codi HTTP 204 (deleted) amb el cos buit

Success

Retorna un objecte Person.

Activitats de l’usuari¶

Representa el conjunt d’activitats creades per un usuari i permet tant llistar-les com crear-ne de noves.

POST /people/{username}/activities¶

Genera una activitat en el sistema. Els objectes d’aquesta activitat són els especificats en el protocol activitystrea.ms.

Query Parameters:

username – (REST) Nom de l’usuari que crea l’activitat
contexts – (Opcional) Per fer que una activitat estigui associada a un context determinat fa falta que enviem una llista d’objectes context (sota la clau contexts) (ja que teòricament, podem fer que l’activitat estigui associada a varis contexts a l’hora), indicant com a objectType el tipus uri i les dades del context com a l’exemple.
object – (Requerit) Per ara només suportat el tipus objectType note. Ha de contindre les claus objectType i content el qual pot tractar-se d’un camp codificat amb HTML, amb tags restringits.

Exemple de petició

{
    "object": {
        "objectType": "note",
        "content": "Testejant la creació d'un canvi d'estatus"
    }
}

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "favoritesCount": 0,
    "object": {
        "content": "Testejant la creaci\u00f3 d'un canvi d'estatus",
        "objectType": "note"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "username": "messi",
        "displayName": "Lionel Messi",
        "objectType": "person"
    },
    "published": "2000-01-01T00:01:00Z",
    "verb": "post",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "messi",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}

Success

Retorna un objecte del tipus Activity.

Error

En cas de que l’usuari actor no sigui el mateix usuari que s’autentica via oAuth
{u'error_description': u"You don't have permission to access xavi resources", u'error': u'Unauthorized'}
En cas que l’usuari no existeixi
{"error_description": "Unknown user: messi", "error": "UnknownUserError"}

Tipus d’activitat suportats:

note (estatus d’usuari)

Tipus d’activitat projectats:

File
Event
Bookmark
Image
Video
Question

En el cas que volguem lligar l’activitat a un context en concret, suposant que l’usuari ha estat previament subscrit a aquest context.

Exemple de petició

{
    "contexts": [
                    {
                        "url": "http://atenea.upc.edu",
                        "objectType": "context"
                     }
                ],
    "object": {
        "objectType": "note",
        "content": "<p>[A] Testejant la creació d'un canvi d'estatus a un context</p>"
    }
}

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "contexts": [
        {
            "url": "http://atenea.upc.edu",
            "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
            "tags": [
                "Assignatura"
            ],
            "displayName": "Atenea",
            "objectType": "context"
        }
    ],
    "favoritesCount": 0,
    "object": {
        "content": "[A] Testejant la creaci\u00f3 d'un canvi d'estatus a un context",
        "objectType": "note"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "username": "messi",
        "displayName": "Lionel Messi",
        "objectType": "person"
    },
    "published": "2000-01-01T00:01:00Z",
    "verb": "post",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "messi",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}

GET /people/{username}/activities¶

Llista totes les activitats de tipus post generades al sistema per part d’un usuari concret.

Query Parameters:
	username – (REST) Identificador d’usuari que crea l’activitat

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

[
    {
        "favorited": false,
        "liked": false,
        "generator": null,
        "contexts": [
            {
                "url": "http://atenea.upc.edu",
                "displayName": "Atenea",
                "objectType": "context",
                "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
                "tags": [
                    "Assignatura"
                ]
            }
        ],
        "favoritesCount": 0,
        "object": {
            "content": "[A] Testejant la creaci\u00f3 d'un canvi d'estatus a un context",
            "objectType": "note"
        },
        "lastComment": "519b00000000000000000002",
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "published": "2000-01-01T00:01:00Z",
        "verb": "post",
        "likes": [],
        "favorites": [],
        "replies": [],
        "deletable": true,
        "objectType": "activity",
        "id": "519b00000000000000000000",
        "likesCount": 0
    },
    {
        "favorited": false,
        "liked": false,
        "generator": null,
        "favoritesCount": 0,
        "object": {
            "content": "Testejant la creaci\u00f3 d'un canvi d'estatus",
            "objectType": "note"
        },
        "lastComment": "519b00000000000000000002",
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "published": "2000-01-01T00:01:00Z",
        "verb": "post",
        "likes": [],
        "favorites": [],
        "replies": [],
        "deletable": true,
        "objectType": "activity",
        "id": "519b00000000000000000000",
        "likesCount": 0
    }
]

Note

En l’ultima resposta esperada hi han tres entrades les dues activitats que hem generat fins ara (amb context, i l’altre sense) i l’activitat que es genera quan es subscriu un usuari a un context, que es tracta com una activitat més.

Success

Retorna una col·lecció d’objectes del tipus Activity.

Error

En cas de que l’usuari actor no sigui el mateix usuari que s’autentica via oAuth
{u'error_description': u"You don't have permission to access xavi resources", u'error': u'Unauthorized'}
En cas que l’usuari no existeixi
{"error_description": "Unknown user: messi", "error": "UnknownUserError"}

Activitats d’un contexte¶

Torna el conjunt d’activitats generades pels usuaris del sistema a un context. L’usuari que fa la petició ha de tindre permisos de lectura com a mínim en el context requerit, de lo contrari se li denegarà l’accés. Típicament s’utilitza per recuperar totes les activitats que els usuaris han associat a un context concret.

GET /contexts/{hash}/activities¶

Llistat de totes les activitats del sistema, filtrada sota algun criteri

Query Parameters:
	hash – (REST) El hash (sha1) de la URL del context sortBy – (Opcional) Tipus d’ordenació que s’aplicarà als resultats. Per defecte és `activities`, i te en compte la data de publicació de l’activitat. L’altre valor possible és `comments` i ordena per la data de l’últim comentari a l’activitat. {"context": "e6847aed3105e85ae603c56eb2790ce85e212997"}

Resposta esperada:

[
    {
        "favorited": false,
        "liked": false,
        "generator": null,
        "contexts": [
            {
                "url": "http://atenea.upc.edu",
                "displayName": "Atenea",
                "objectType": "context",
                "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
                "tags": [
                    "Assignatura"
                ]
            }
        ],
        "favoritesCount": 0,
        "object": {
            "content": "[A] Testejant la creaci\u00f3 d'un canvi d'estatus a un context",
            "objectType": "note"
        },
        "lastComment": "519b00000000000000000002",
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "published": "2000-01-01T00:01:00Z",
        "verb": "post",
        "likes": [],
        "favorites": [],
        "replies": [],
        "deletable": true,
        "objectType": "activity",
        "id": "519b00000000000000000000",
        "likesCount": 0
    }
]

Success: Retorna una col·lecció d’objectes del tipus Activity.

Timeline¶

Representa el flux d’activitat global de l’usuari, que comprèn les activitats que ha creat, les activitats de les persones a qui segueix i les activitats generades sota els contexts concrets al qual està subscrit, directa o indirectament.

GET /people/{username}/timeline¶

Llistat de totes les activitats del timeline de l’usuari. Actualment filtra les activitats i només mostra les de tipus post.

Query Parameters:
	username – (REST) Nom de l’usuari que del qual volem el llistat sortBy – (Opcional) Tipus d’ordenació que s’aplicarà als resultats. Per defecte és `activities`, i te en compte la data de publicació de l’activitat. L’altre valor possible és `comments` i ordena per la data de l’últim comentari a l’activitat.

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

[
    {
        "favorited": false,
        "liked": false,
        "generator": null,
        "contexts": [
            {
                "url": "http://atenea.upc.edu",
                "displayName": "Atenea",
                "objectType": "context",
                "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
                "tags": [
                    "Assignatura"
                ]
            }
        ],
        "favoritesCount": 0,
        "object": {
            "content": "[A] Testejant la creaci\u00f3 d'un canvi d'estatus a un context",
            "objectType": "note"
        },
        "lastComment": "519b00000000000000000002",
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "published": "2000-01-01T00:01:00Z",
        "verb": "post",
        "likes": [],
        "favorites": [],
        "replies": [],
        "deletable": true,
        "objectType": "activity",
        "id": "519b00000000000000000000",
        "likesCount": 0
    },
    {
        "favorited": false,
        "liked": false,
        "generator": null,
        "favoritesCount": 0,
        "object": {
            "content": "Testejant la creaci\u00f3 d'un canvi d'estatus",
            "objectType": "note"
        },
        "lastComment": "519b00000000000000000002",
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "published": "2000-01-01T00:01:00Z",
        "verb": "post",
        "likes": [],
        "favorites": [],
        "replies": [],
        "deletable": true,
        "objectType": "activity",
        "id": "519b00000000000000000000",
        "likesCount": 0
    }
]

Success

Retorna una col·lecció d’objectes del tipus Activity.

Comentaris d’una activitat¶

Representa el conjunt de comentaris fets a una activitat.

POST /activities/{activity}/comments¶

Afegeix un comentari a una activitat ja existent al sistema. Aquest servei crea el comentari pròpiament dit dins de l’activitat i genera una activitat nova del tipus comment (l’usuari ha comentat l’activitat... )

Query Parameters:
	activity – (REST) Ha de ser un identificador vàlid d’una activitat existent, per exemple: 4e6eefc5aceee9210d000004 object – (Requerit) El tipus (`objectType`) d’una activitat comentari ha de ser comment. Ha de contindre les claus `objectType` i `content`.

Exemple de petició

{
    "object": {
        "objectType": "comment",
        "content": "<p>[C] Testejant un comentari nou a una activitat</p>"
    }
}

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "favoritesCount": 0,
    "object": {
        "content": "[C] Testejant un comentari nou a una activitat",
        "inReplyTo": [
            {
                "contexts": [],
                "id": "519b00000000000000000000",
                "objectType": "note"
            }
        ],
        "keywords": [
            "testejant",
            "comentari",
            "nou",
            "una",
            "activitat"
        ],
        "objectType": "comment"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "username": "messi",
        "displayName": "Lionel Messi",
        "objectType": "person"
    },
    "published": "2000-01-01T00:01:00Z",
    "keywords": [],
    "verb": "comment",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "messi",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}

Success

Retorna l’objecte Activity del comentari.

GET /activities/{activity}/comments¶

Llista tots els comentaris d’una activitat

Query Parameters:
	activity – (REST) ha de ser un identificador vàlid d’una activitat existent, per exemple: 4e6eefc5aceee9210d000004

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

[
    {
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "content": "[C] Testejant un comentari nou a una activitat",
        "deletable": true,
        "published": "2000-01-01T00:01:00Z",
        "id": "519b00000000000000000000",
        "objectType": "comment"
    }
]

Success

Retorna una col·lecció d’objectes del tipus Comment

Subscripcions¶

GET /contexts/public¶

Dona una llista de tots els contextes als qual un usuari es pot subscriure lliurement

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

[
    {
        "displayName": "Atenea",
        "tags": [
            "Assignatura"
        ],
        "url": "http://atenea.upc.edu",
        "published": "2000-01-01T00:01:00Z",
        "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
        "permissions": {
            "write": "public",
            "subscribe": "public",
            "read": "public",
            "invite": "subscribed"
        },
        "id": "519b00000000000000000000",
        "objectType": "context"
    },
    {
        "displayName": "Atenea A",
        "tags": [
            "Assignatura"
        ],
        "url": "http://atenea.upc.edu/A",
        "published": "2000-01-01T00:01:00Z",
        "hash": "90c8f28a7867fbad7a2359c6427ae8798a37ff07",
        "permissions": {
            "write": "public",
            "subscribe": "public",
            "read": "public",
            "invite": "subscribed"
        },
        "id": "519b00000000000000000000",
        "objectType": "context"
    }
]

Success

Retorna un objecte del tipus Activity.

POST /people/{username}/subscriptions¶

Subscriu l’usuari a un context determinat. El context al qual es vol subscriure l’usuari ha de ser de tipus public, sinó obtindrem un error d’autorització 401 Unauthorized

Query Parameters:
	username – (REST) L’identificador de l’usuari al sistema. contexts – (Requerit) Tipus d’objecte al qual ens volem subscriure, en aquest cas del tipus context. Hem de proporcionar un objecte amb les claus `objectType` i el valor context, i la dada `url` del context.

Exemple de petició

{
    "object": {
        "objectType": "context",
        "url": "http://atenea.upc.edu/A"
    }
}

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "favoritesCount": 0,
    "object": {
        "url": "http://atenea.upc.edu/A",
        "objectType": "context"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "username": "messi",
        "displayName": "Lionel Messi",
        "objectType": "person"
    },
    "published": "2000-01-01T00:01:00Z",
    "keywords": [],
    "verb": "subscribe",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "messi",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}

Success

Retorna un objecte del tipus Activity.

Error

En cas que l’usuari no existeixi

{ "error_description": "Unknown user: messi", "error": "UnknownUserError" }

Representa el conjunt de contextes als quals esta subscrit un usuari.

GET /people/{username}/subscriptions¶

Torna totes les subscripcions d’un usuari

Query Parameters:
	username – (REST) L’identificador de l’usuari al sistema

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

[
    {
        "displayName": "Atenea",
        "tags": [
            "Assignatura"
        ],
        "url": "http://atenea.upc.edu",
        "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
        "objectType": "context",
        "permissions": [
            "read",
            "write",
            "unsubscribe",
            "invite"
        ]
    },
    {
        "displayName": "Atenea A",
        "tags": [
            "Assignatura"
        ],
        "url": "http://atenea.upc.edu/A",
        "hash": "90c8f28a7867fbad7a2359c6427ae8798a37ff07",
        "objectType": "context",
        "permissions": [
            "read",
            "write",
            "unsubscribe",
            "invite"
        ]
    }
]

DELETE /people/{username}/subscriptions/{hash}¶

Elimina la subscripció d’un usuari, si l’usuari té permis per dessubscriure’s. NO esborra les activitats que s’hagin creat previament al context del qual ens hem dessubscrit. Tot i que les activitats que queden a la base de dades no es poden consultar directament, en el timeline de un usuari coninuarà veient les activitats que va crear ell.

Query Parameters:
	username – (REST) L’identificador de l’usuari al sistema. hash – (REST) El hash del context la subscripció al qual es vol esborrar. Aquest hash es calcula fent una suma de verificació sha1 dels paràmetres del context

Exemple de petició

Aquesta petició no te cos.

Missatges i converses¶

El MAX implementa des de la seva versió 3.0 la funcionalitat de missatgeria instantània asíncrona entre els seus usuaris.

Les converses tenen un limit de 20 participants.
Les converses tenen un propietari, que és l’usuari que va crear la conversa.
El propietari de la conversa pot afegir més gent a la conversa.
El propietari de la conversa pot fer fora usuaris de la conversa.
El propietari de la conversa NO pot marxar d’una conversa
Els participants d’una conversa poden marxar sempre que vulguin de la conversa, els seus missatges no s’esborren

Aquests són els serveis associats.

POST /conversations¶

Crea una conversa nova, hi subscriu tots els participants especificats, i afegeix el missatge a la conversa.

Query Parameters:

contexts – (Requerit) Tipus d’objecte al qual ens volem subscriure (en aquest cas conversation). Hem de proporcionar un objecte amb les claus objectType i el valor conversation, i la llista de participants com a l’exemple
object – (Requerit) Tipus d’objecte de la conversa. Hem de proporcionar un objecte (per ara només es permet el tipus note) i el contingut amb les dades content amb el cos del missatge propiament dit

Exemple de petició

{
    "contexts": [
        {
            "objectType":"conversation",
            "participants": ["messi", "xavi"]
        }
    ],
    "object": {
        "objectType": "note",
        "content": "Nos espera una gran temporada, no es cierto?"
    }
}

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "contexts": [
        {
            "displayName": "messi, xavi",
            "id": "519b00000000000000000000",
            "objectType": "conversation"
        }
    ],
    "object": {
        "content": "Nos espera una gran temporada, no es cierto?",
        "keywords": [
            "nos",
            "espera",
            "una",
            "gran",
            "temporada",
            "cierto",
            "messi"
        ],
        "objectType": "note"
    },
    "replies": [],
    "actor": {
        "username": "messi",
        "displayName": "Lionel Messi",
        "objectType": "person"
    },
    "keywords": [],
    "verb": "post",
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "id": "519b00000000000000000000",
    "objectType": "message"
}

Success

Retorna l’objecte Message (activitat).

GET /conversations/{hash}/messages¶

Retorna tots els missatges d’una conversa

Query Parameters:
	hash – (REST) El hash de la conversa en concret. Aquest hash es calcula fent una suma de verificació sha1 de la llista de participants (ordenada alfabèticament i sense espais) de la conversa

Exemple de petició

Aquesta petició no te cos.

Resposta esperada:

[
    {
        "generator": null,
        "contexts": [
            {
                "displayName": "messi, xavi",
                "id": "519b00000000000000000000",
                "objectType": "conversation"
            }
        ],
        "object": {
            "content": "Nos espera una gran temporada, no es cierto?",
            "objectType": "note"
        },
        "replies": [],
        "actor": {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        "verb": "post",
        "published": "2000-01-01T00:01:00Z",
        "id": "519b00000000000000000000",
        "objectType": "message"
    }
]

Success

Retorna una llista d’objectes Message

GET /conversations¶

Retorna totes les converses de l’actor que faci la petició

Exemple de petició

Aquesta petició no te cos.

Resposta esperada:

[
    {
        "displayName": "xavi",
        "creator": "messi",
        "messages": 1,
        "participants": [
            {
                "username": "messi",
                "displayName": "Lionel Messi",
                "objectType": "person"
            },
            {
                "username": "xavi",
                "displayName": "xavi",
                "objectType": "person"
            }
        ],
        "lastMessage": {
            "content": "Nos espera una gran temporada, no es cierto?",
            "published": "2000-01-01T00:01:00Z"
        },
        "published": "2000-01-01T00:01:00Z",
        "owner": "messi",
        "permissions": {
            "read": "subscribed",
            "write": "subscribed",
            "unsubscribe": "public",
            "invite": "restricted",
            "subscribe": "restricted"
        },
        "id": "519b00000000000000000000",
        "objectType": "conversation"
    }
]

Success

Retorna una llista d’objectes del tipus Conversation.

GET /conversations/{id}¶

Retorna una conversa

Query Parameters:
	id – (REST) L’identificador d’una conversa. el podem obtenir en la resposta al crear una conversa nova, o en la llista de converses d’un usuari.

Exemple de petició

Aquesta petició no te cos.

Resposta esperada:

{
    "displayName": "xavi",
    "creator": "messi",
    "participants": [
        {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        {
            "username": "xavi",
            "displayName": "xavi",
            "objectType": "person"
        }
    ],
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "permissions": {
        "read": "subscribed",
        "write": "subscribed",
        "unsubscribe": "public",
        "invite": "restricted",
        "subscribe": "restricted"
    },
    "id": "519b00000000000000000000",
    "objectType": "conversation"
}

Success

Retorna un objecte del tipus Conversation.

PUT /conversations/{id}¶

Modifica una conversa

Query Parameters:
	id – (REST) L’identificador d’una conversa. el podem obtenir en la resposta al crear una conversa nova, o en la llista de converses d’un usuari. displayName – El nom visible de la conversa, només visible en converses de més de 2 participants.

Exemple de petició

{
    displayName: 'Nou nom'
}

Resposta esperada:

{
    "displayName": "xavi",
    "creator": "messi",
    "participants": [
        {
            "username": "messi",
            "displayName": "Lionel Messi",
            "objectType": "person"
        },
        {
            "username": "xavi",
            "displayName": "xavi",
            "objectType": "person"
        }
    ],
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "permissions": {
        "read": "subscribed",
        "write": "subscribed",
        "unsubscribe": "public",
        "invite": "restricted",
        "subscribe": "restricted"
    },
    "id": "519b00000000000000000000",
    "objectType": "conversation"
}

Success

Retorna un objecte del tipus Conversation.

POST /conversations/{hash}/messages¶

Crea un missatge nou a una conversa ja existent

Query Parameters:
	hash – (REST) El hash de la conversa en concret. Aquest hash es calcula fent una suma de verificació sha1 de la llista de participants (ordenada alfabèticament i sense espais) de la conversa

Exemple de petició

{
    "object": {
        "objectType": "note",
        "content": "M'agrada Taradell!"
    }
}

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "contexts": [
        {
            "displayName": "messi, xavi",
            "id": "519b00000000000000000000",
            "objectType": "conversation"
        }
    ],
    "object": {
        "content": "M'agrada Taradell!",
        "keywords": [
            "agrada",
            "taradell",
            "messi"
        ],
        "objectType": "note"
    },
    "replies": [],
    "actor": {
        "username": "messi",
        "displayName": "Lionel Messi",
        "objectType": "person"
    },
    "keywords": [],
    "verb": "post",
    "published": "2000-01-01T00:01:00Z",
    "owner": "messi",
    "id": "519b00000000000000000000",
    "objectType": "message"
}

Success

Retorna l’objecte Message (activitat).

POST /people/{username}/conversations/{id}¶

Afegeix un usuari a una conversa. L’usuari propietari de la conversa és l’únic que ho pot fer. Hi ha un limit de 20 participants per conversa.

Query Parameters:
	username – (REST) L’usuari que es vol afegir a la conversa id – (REST) L’identificador d’una conversa. el podem obtenir en la resposta al crear una conversa nova, o en la llista de converses d’un usuari.

Exemple de petició

Aquesta petició no te cos.

Resposta esperada:

{
    "generator": null,
    "creator": "messi",
    "favoritesCount": 0,
    "object": {
        "participants": [
            {
                "username": "messi",
                "displayName": "Lionel Messi",
                "objectType": "person"
            },
            {
                "username": "xavi",
                "displayName": "xavi",
                "objectType": "person"
            },
            {
                "username": "nouusuari",
                "displayName": "nouusuari",
                "objectType": "person"
            }
        ],
        "id": "519b00000000000000000000",
        "objectType": "conversation"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "username": "nouusuari",
        "displayName": "nouusuari",
        "objectType": "person"
    },
    "published": "2000-01-01T00:01:00Z",
    "keywords": [],
    "verb": "subscribe",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "nouusuari",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}

Retorna un codi HTTP 201 (created) amb la subscripció, o un HTTP 401 (Unauthorized) si l’usuari no és el propietari. Si sobrepassem el límit obtindrem un HTTP 403 (Forbidden)

DELETE /people/{username}/conversations/{id}¶

Treu un usuari d’una conversa. Ho pot fer qualsevol participant de la conversa excepte el propietari.

Query Parameters:
	username – (REST) L’usuari que es vol afegir a la conversa id – (REST) L’identificador d’una conversa. el podem obtenir en la resposta al crear una conversa nova, o en la llista de converses d’un usuari.

Exemple de petició

Aquesta petició no te cos.

Resposta esperada:

Retorna un codi HTTP 204 (deleted) amb el cos buit, o un HTTP 401 (Unauthorized) si l’usuari no és el propietari

DELETE /conversations/{id}¶

Elimina una conversa

Elimina una conversa i tots els seus missatges de forma permanent. L’usuari propietari de la conversa és ĺ’únic que pot eliminarla.

Query Parameters:
	id – (REST) L’identificador d’una conversa. el podem obtenir en la resposta al crear una conversa nova, o en la llista de converses d’un usuari.

Exemple de petició

Aquesta petició no te cos.

Resposta esperada:

Retorna un codi HTTP 204 (deleted) amb el cos buit, o un HTTP 401 (Unauthorized) si l’usuari no és el propietari

Contextos¶

Tot i que els serveis associats a contextos són majoritàriament d’accés restringit, els que són accessibles per usuaris normals estàn documentats aquí

GET /contexts/public¶

Dona una llista de tots els contextes als qual un usuari es pot subscriure lliurement

Exemple de petició

Aquesta petició no necessita cos.

Resposta esperada:

[
    {
        "displayName": "Atenea",
        "tags": [
            "Assignatura"
        ],
        "url": "http://atenea.upc.edu",
        "published": "2000-01-01T00:01:00Z",
        "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
        "permissions": {
            "write": "public",
            "subscribe": "public",
            "read": "public",
            "invite": "subscribed"
        },
        "id": "519b00000000000000000000",
        "objectType": "context"
    },
    {
        "displayName": "Atenea A",
        "tags": [
            "Assignatura"
        ],
        "url": "http://atenea.upc.edu/A",
        "published": "2000-01-01T00:01:00Z",
        "hash": "90c8f28a7867fbad7a2359c6427ae8798a37ff07",
        "permissions": {
            "write": "public",
            "subscribe": "public",
            "read": "public",
            "invite": "subscribed"
        },
        "id": "519b00000000000000000000",
        "objectType": "context"
    }
]

Success

Retorna un objecte del tipus Context.

GET /contexts/{hash}/avatar¶

Retorna la imatge que li correspon al context depenent del usuari de Twitter que te assignat. Si no en te cap, retorna una imatge estàndar. Per ara només està implementada la integració amb Twitter i dissenyat per quan un context vol parlar impersonat a l’activitat del seu propi context. Per exemple, una assignatura.

Aquest és un servei públic, no és necessaria la autenticació oauth.

Query Parameters:
	hash – (REST) El hash del context en concret. Aquest hash es calcula fent una suma de verificació sha1 de la URL del context.

Success

Retorna la imatge del context.