API REST (restringida)

Aquesta és la llista de serveis REST que queda fora de la operativa d’usuari i de la UI. Està dissenyada per l’ús d’un usuari restringit d’aplicació pel qual prèviament se li ha d’haver donat permisos al sistema. Aquest usuari no te cap privilegi addicional sobre el sistema que el que s’exposa en la descripció de cada servei.

Usuaris

POST /people/{username}

Crea un 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": "messi", "displayName": "Lionel Messi"}

Resposta esperada

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

Success

Retorna un objecte Person.

Contexts

POST /contexts

Crea un context al sistema.

Query Parameters:  

• objectType – (Obligatori) De moment se suporta el tipus context
• url – La URL amb la qual s’identifica el context.
• displayName – (Opcional) El nom per mostrar a la UI. Si no s’especifica, es mostrarà la url
• twitterHashtag – (Opcional) El hashtag (#) que identifica els posts a Twitter com a posts del context. Tots els posts d’usuaris del sistema i amb permisos al context amb compta de twitter informada s’importaran i apareixeran a l’activitat del context.
• twitterUsername – (Opcional) El nom d’usuari de Twitter que aquest context té assignat. Qualsevol post fet a Twitter amb aquest usuari s’importarà i apareixerà a l’activitat del context com activitat (impersonat) del propi context.
• permissions – (Opcional) Els permisos i parametrització de seguretat relacionada amb el context. Per defecte els contextos són públics a tots els efectes.
• tags – (Opcional) Llista de tags per categoritzar un contexte

Cos de la petició

{
    "url": "http://atenea.upc.edu",
    "objectType": "context",
    "displayName": "Atenea",
    "tags": ["Assignatura"]
}

Resposta esperada

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

Success

Retorna l’objecte Context.

GET /contexts

Cerca un context al sistema

Tags:(Opcional)

Cos de la petició

{
    "tags": "Assignatura"
}

Resposta esperada

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

PUT /contexts/{hash}

Modifica un context al sistema. Els camps que es poden modificar queden descrits a continuació

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.
• displayName – (Opcional) El nom per mostrar a la UI.
• twitterHashtag – (Opcional) El hashtag (#) que identifica els posts a Twitter com a posts del context. Tots els posts d’usuaris del sistema i amb permisos al context amb compta de twitter informada s’importaran i apareixeran a l’activitat del context.
• twitterUsername – (Opcional) El nom d’usuari de Twitter que aquest context té assignat. Qualsevol post fet a Twitter amb aquest usuari s’importarà i apareixerà a l’activitat del context com activitat (impersonat) del propi context.
• tags – (Opcional) Llista de tags per categoritzar un contexte

Cos de la petició

{ "twitterHashtag": "assignatura1" }

Resposta esperada

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

Success

Retorna l’objecte Context modificat.

GET /contexts/{hash}

Retorna la informació d’un objecte Context.

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.

Cos de la petició

Aquesta petició no te cos.

Resposta esperada

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

Success

Retorna un objecte del tipus Context.

DELETE /contexts/{hash}

Esborra un objecte Context i les subscripcions de tots els usuaris subscrits a aquell contexte NO esborra les activitats que s’hagin creat previament al context esborrat. 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:  

• hash – (REST) El hash del context en concret. Aquest hash es calcula fent una suma de verificació sha1 dels paràmetres del context

Cos de la petició

Aquesta petició no te cos.

Subscripcions

POST /people/{username}/subscriptions

Subscriu l’usuari a un context determinat.

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.

Cos de la petició

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

Resposta esperada

{
    "generator": null,
    "creator": "test_manager",
    "favoritesCount": 0,
    "object": {
        "url": "http://atenea.upc.edu",
        "objectType": "context"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "username": "messi",
        "displayName": "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" }

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

Elimina la subscripció d’un usuari Esborra un objecte Context i les subscripcions de tots els usuaris subscrits a aquell contexte. 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

Cos de la petició

Aquesta petició no te cos.

Permisos a contexts

Sobre els objectes context es poden otorgar o revocar permisos a usuaris del sistema. Aquests permisos són qualsevol dels permisos definitsen profunditat en l’apartat de permisos. Els permisos otorgats amb aquest sistema són persistents, per tant un canvi de permisos en els valors per defecte del context no afecta als permisos afegits/denegats.

Per tornar un usuari am permisos afegits/denegats als valors per defecte del contexte, haurem de resetejar els permisos d’aquell usuari en aquell contexte.

Un usuari pot tenir un permis per defecte, i tot i aixi otorgar-li el permis de manera persistent, de manera que a partir de llavors, no el pot perdre exepte per eliminació explícita.

PUT /contexts/{hash}/permissions/{username}/{permission}

Afegeix els permisos per un context donat un identificador d’usuari i el permís que li vols donar, de forma persistent.

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.
• username – (REST) L’identificador del nou usuari al sistema
• permission – (REST) El permís que li volem otorgar a l’usuari

Cos de la petició

Aquesta petició no te cos.

Resposta esperada

{
    "twitterHashtag": "assignatura1",
    "displayName": "Atenea",
    "url": "http://atenea.upc.edu",
    "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
    "objectType": "context",
    "permissions": [
        "read",
        "write",
        "unsubscribe"
    ]
}

Success

Si el permís ja estava otorgat, el codi HTTP de resposta és 200, si no, torna un 201. En el cos, torna la subscripció modificada.

DELETE /contexts/{hash}/permissions/{username}/{permission}

Denega els permis per un context donat un identificador d’usuari i el permís que li vols donar de manera persistent

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.
• username – (REST) L’identificador del nou usuari al sistema
• permission – (REST) El permís que li volem otorgar a l’usuari

Cos de la petició

Aquesta petició no te cos.

Resposta esperada

{
    "twitterHashtag": "assignatura1",
    "displayName": "Atenea",
    "url": "http://atenea.upc.edu",
    "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
    "permissions": [
        "read",
        "unsubscribe"
    ],
    "objectType": "context"
}

POST /contexts/{hash}/permissions/{username}/defaults

Reseteja els permisos d’un usuari en un contexte als per defecte d’aquell contexte. Això elimina qualsevol permis persistent afegit o denegat anteriorment.

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.
• username – (REST) L’identificador del nou usuari al sistema

Cos de la petició

Aquesta petició no te cos.

Resposta esperada

{
    "twitterHashtag": "assignatura1",
    "displayName": "Atenea",
    "url": "http://atenea.upc.edu",
    "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
    "permissions": [
        "read",
        "write",
        "unsubscribe"
    ],
    "objectType": "context"
}

Activitats

POST /people/{username}/activities

Afegeix una activitat en nom d’un usuari qualsevol

Query Parameters:  

• username – (REST) El nom d’usuari en nom del qual es crearà 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 context 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 que pot tractar-se d’un camp codificat amb HTML

Cos de la 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": "test_manager",
    "contexts": [
        {
            "twitterHashtag": "assignatura1",
            "displayName": "Atenea",
            "tags": [
                "Assignatura"
            ],
            "url": "http://atenea.upc.edu",
            "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
            "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": "messi",
        "objectType": "person"
    },
    "published": "2000-01-01T00:01:00Z",
    "verb": "post",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "messi",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}

POST /contexts/{hash}/activities

Afegeix una activitat en nom d’un context qualsevol

Query Parameters:  

• hash – (REST) El hash del context en nom del qual es crearà l’activitat
• contexts – (Requerit) 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 context i les dades del context com a l’exemple. En aquest cas d’ús el contexte especificat aquí ha de ser el mateix que l’especificat al paràmetre {hash}
• object – (Requerit) Per ara només suportat el tipus (objectType) note. Ha de contindre les claus objectType i content que pot tractar-se d’un camp codificat amb HTML.

Cos de la 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": "test_manager",
    "contexts": [
        {
            "url": "http://atenea.upc.edu",
            "displayName": "Atenea",
            "tags": [
                "Assignatura"
            ],
            "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
            "objectType": "context"
        }
    ],
    "favoritesCount": 0,
    "object": {
        "content": "[A] Testejant la creaci\u00f3 d'un canvi d'estatus a un context",
        "keywords": [
            "testejant",
            "creaci\u00f3",
            "canvi",
            "estatus",
            "context"
        ],
        "objectType": "note"
    },
    "lastComment": "519b00000000000000000002",
    "actor": {
        "url": "http://atenea.upc.edu",
        "hash": "e6847aed3105e85ae603c56eb2790ce85e212997",
        "displayName": "Atenea",
        "objectType": "context"
    },
    "published": "2000-01-01T00:01:00Z",
    "keywords": [
        "canvi",
        "creaci\u00f3",
        "estatus",
        "testejant",
        "context"
    ],
    "verb": "post",
    "likes": [],
    "favorites": [],
    "replies": [],
    "owner": "test_manager",
    "likesCount": 0,
    "id": "519b00000000000000000000",
    "objectType": "activity"
}