Wouso API’s documentation¶

The wouso API is a REST web service using OAuth v1.0 authentication, allowing your application to interact with a wouso instance.

A demo python library interfacing with the api is available here: http://github.com/rosedu/wouso-extras .

Wouso API-enabled instances¶

The updated list of wouso instances is available at: http://wouso.cs.pub.ro/instances.json . You need an user account on the instance in order to use its api.

Basic information:¶

GET /api/¶

Api information.

Example response:

{
    "api_version": "1",
    "title": "World of USO",
    "authenticated": false
}

GET /api/info/online/¶

Fetch information about players seen online in the last 10 minutes.

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
    {
        "first_name": "Alex",
        "last_name": "Eftimie2",
        "nickname": "admin",
        "id": 1,
        "last_seen": "2013-02-17T18:45:56.643"
    }
]

Variation: /api/info/online/list/, with response: [ “admin”, ...]

GET /api/info/nickname/¶: Return the current player’s nickname.

POST /api/info/nickname/¶

Attempt to change the nickname of the authenticated player. The nickname is sent as the payload to the POST request. Possible errors: “no nickname”, “nickname already in use”.

Example request

POST /api/info/nickname/ HTTP/1.1
Host: wouso-next.rosedu.org
...

nickname=myl33tnickname

Example response:

{ "success": True }
{ "success": False, "error": "Nickname in use" }

Notifications¶

POST /api/notifications/register/¶: Register a new Android device for push notifications. POST data must contain registration_id.

POST /api/notifications/devices/¶: List registered Android devices which will receive push notifications.

GET /api/notifications/all/¶

Return the notification count for the requesting user.

Example request:

GET /api/notifications/all/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "count":    0
}

Status Codes:	200 – no error 401 – not authorized

Player information¶

GET /api/player/(player_id)/info/¶

Returns information about current (authenticated) user.

Example request:

GET /api/player/1/info/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    username: "alex.eftimie",
    first_name: "Alex",
    last_name: "Eftimie",
    avatar:  "http://www.gravatar.com/avatar/d43fad239b039cebdb4206cdc692f314.jpg",
    level: {
        name: "level-1",
        title: "Level 1",
        image: "",
        percents: 100,
        id: 2
    },
    level_no: 1,
    level_progress: {
        percent: 50,
        next_level: 2,
        points_gained: 55,
        points_left: 45,
    }
    race: "Oxynia",
    race_id: "1",
    race_slug: "ca",
    group: "CA311",
    email: "alex@rosedu.org",
    points: 0,
    gold: 0,
}

Status Codes:	200 – no error 401 – not authorized 404 – current user doesn’t have a profile

GET /api/player/info/¶: Returns information about current (authenticated) user. Same response as /api/player/(player_id)/info/.

GET /api/search/<query string>/¶

Search for players matching query string.

Example request:

GET /api/search/alex/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
    {
        "id":   1,
        "first_name": "Alex",
        "last_name": "Eftimie",
    }
]

Status Codes:	200 – no error 401 – not authorized

Magic and Bazaar¶

GET /api/bazaar/¶

Returns a list of all available spells for buying.

Example request:

GET /api/bazaar/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
     [
         {
             id: 30,
             name: "challenge-cannot-be-challenged",
             title: "Nu poate fi provocat",
             type: "n",
             due_days: 3,
             image_url: "/static/upload/challenge.png",
             price: 10,
             percents: 100,
             description: "Nu permite provocarea jucătorului pe care este aplicată."
         },
     ]
 }

Status Codes:	200 – no error 401 – not authorized

GET /api/bazaar/inventory/¶

Returns a list of spells in current authenticated user’s inventory, also active and cast lists.

Example request:

GET /api/bazaar/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    spells_cast: [
        {
            due: "2013-04-04T15:50:03.643",
            spell_id: 1,
            spell_title: "Disguise -25%",
            spell_name: "top-disguise",
            image_url: "/static/image.png",
            player_id: 1,
            player: "admin"
        }
    ],
    spells_available: [
        {
            spell_id: 2,
            spell_name: "top-disguise",
            spell_title: "Disguise -15%",
            image_url: "/static/image.png",
            amount: 1
        }
    ],
    spells_onme: [
        {
            due: "2013-04-04T15:50:03.643",
            spell_id: 1,
            spell_title: "Disguise -25%",
            spell_name: "top-disguise",
            image_url: "/static/image.png",
            source_id: 1,
            source: "admin"
        }
    ]
}

Status Codes:	200 – no error 401 – not authorized 404 – current user does not have a profile

POST /api/bazaar/buy/¶

Attempts to buy a spell sent as POST parameter. Returns success or error.

Posible errors:

Spell not provided
No such spell
Insufficient gold

Example request:

POST /api/bazaar/buy/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"
Content-Type: application/x-www-form-urlencoded
Content-Length: 7

spell=1

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    success: true
}

Status Codes:	200 – no error 401 – not authorized

POST /api/bazaar/exchange/gold/points/¶

Attempts to exchange an amount sent as POST parameter. Returns success or error.

Posible errors:

Invalid Amount
Insufficient Amount

POST /api/bazaar/exchange/points/gold/¶: The same as gold to points.

POST /api/player/<player_id>/cast/¶

Cast a spell given as POST parameter to player_id. Accepts an optional days parameter.

Example request:

POST /api/player/2/cast/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Content-Type: application/x-www-form-urlencoded
Content-Length: 7

spell=1&days=2

Example response:

{
    success: true
}

Top¶

GET /api/top/race/¶

Returns top races in the game, ordered by points.

Example response:

[
    {
        title: "Others",
        points: 2008,
        id: 1,
        name: "Others"
    },
    {
        title: "Zota",
        points: 315,
        id: 4,
        name: "CB"
    }
    ...
]

GET /api/top/race/(race_id)/group/¶: Returns top groups in selected race, ordered by points.

GET /api/top/race/(race_id)/player/¶: Returns top players in selected race.

GET /api/top/group/¶: Returns top groups in the game, ordered by points.

GET /api/top/group/(group_id)/player/¶: Returns top players in selected group.

GET /api/top/player/¶: Returns top players in the game.

Races and Groups¶

GET /api/race/¶: List all races defined in wouso.

GET /api/race/(race_id)/members/¶: All players in selected race.

GET /api/race/(race_id)/groups/¶: All groups in selected race.

GET /api/group/¶: List all groups defined in wouso.

GET /api/group/(group_id)/¶: Returns information about the group: name, member count, rank.

GET /api/group/(group_id)/members/¶: All players in selected group.

GET /api/group/(group_id)/activity/¶: Returns latest activity for group members.

GET /api/group/(group_id)/evolution/¶: Returns group points evolution.

Messages¶

GET /api/messages/(type)¶

Returns all messages by type:

all
sent
recv

Each message contains the subject, text, date, sender and receiver (both names and ids) and reply_to id.

The reply_to parameter refers to another message (not an user), for conversations. If it’s null, then the message is the first in a conversation.

Example response:

[
    {
        "from": "Gică Popescu",
        "from_id": 2,
        "to": "admin",
        "to_id": 1,
        "id": 4,
        "subject": "Re: Ce faci măi?",
        "date": "2013-09-27T18:02:47.364",
        "text": "bine facem",
        "read": false,
        "reply_to": 3
    }
]

POST /api/messages/send/¶

Sends a message, using POST parameters:

receiver (*mandatory, id or username)
text (*mandatory)
subject
reply_to (id of the message to reply_to, not of the sender)

POST /api/messages/(action)/(msg_id)/¶

Apply an action on a message, if it is received by user. Available actions are:

setread
setunread
archive
unarchive

Games¶

Question of the Day¶

GET /api/qotd/today/¶

Get Question of The Day for current date.

Example request:

GET /api/qotd/today/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    text:       "What is this?"
    answers: {
        10: "yes",
        11: "no",
        12: "other"
    }
    had_answered: false
}

Status Codes:	200 – no error 401 – not authorized 404 – user doesn’t have a profile

POST /api/qotd/today/¶

Attempt to response QotD, by sending the answer id as POST data. In case of error, success is set to false, and an error message is provided.

Error messages:

No question for today
User already answered
Answer not provided
Invalid answer

Example request:

POST /api/qotd/today/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"
Content-Type: application/x-www-form-urlencoded
Content-Length: 9

answer=11

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    success:    true
    correct:    true
}

Second example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    success:    false
    error: "User already answered"
}

Status Codes:	200 – no error 401 – not authorized 404 – user doesn’t have a profile

Challenge¶

GET /api/challenge/list/¶: Return a list of all active challenges.

GET /api/challenge/launch/(player_id)/¶: Launch a new challenge against given player.

GET /api/challenge/(challenge_id)/accept/¶: Accept specific challenge.

GET /api/challenge/(challenge_id)/refuse/¶: Refuse specific challenge.

GET /api/challenge/(challenge_id)/cancel/¶: Cancel specific challenge.

GET /api/challenge/(challenge_id)/¶

Return information and questions (content) for given challenge. Also set it as started for user requesting.

Example response:

{
    success: true,
    status: "A",
    date: "2012-06-19 19:59:32"
    from: "test",
    to: "admin",
    seconds: 61,
    questions: {
        21: {
            text: "S Which is the codename of current WoUSO devel version?",
            answers: {
                81: "Piranha",
                82: "4",
                83: "no codename",
                84: "nom nom nom"
            }
        },
        26: {
            text: "S In lumea UNIX un proces poate avea un singur proces parinte. In momentul in care parintele este omorat printr-ul semnal SIGKILL, procesul copil",
            answers: {
                101: "este automat omorat si el",
                102: "devine orfan, isi termina executia, fara a fi adoptat de nimeni",
                103: "devine orfan si este automat adoptat de parintele parintelui (bunicul procesului)",
                104: "devine orfan si este automat adoptat de procesul "init""
            }
        }
    }
}

POST /api/challenge/(challenge_id)/¶

Post answers to a challenge. These must be mapped as a list of POST parameters, using the question id as key, and answers ids comma separated.

Example request:

POST /api/challenge/1/ HTTP/1.1
Host: wouso-next.rosedu.org
Accept: application/json, text/javascript
Authorization: OAuth oauth_version="1.0",oauth_nonce="a1df9b758e16eaebe8a2208d1e210bfb",oauth_timestamp="1312861474",oauth_consumer_key="xxxxxx",oauth_token="xxxxx",oauth_signature_method="PLAINTEXT",oauth_signature="xxxxxx"
Content-Type: application/x-www-form-urlencoded
Content-Length: 25

12=1&13=4&14=5,6&16=9&17=

This request sends the following answers:

{
    12: [ 1 ],
    13: [ 4 ],
    14: [ 5, 6 ],
    16: [ 9 ],
    17: [ ]
}

Quest¶

The calls in the /admin/ namespace must be made by users having quest.change_quest permission set.

GET /api/quest/admin/¶

Return a list of quests.

Example response:

[
   {
        id: 1,
        title: "Gioconda",
        start: "2012-11-08T14:11:42",
        end: "2013-11-08T16:00:00"
   }
]

GET /api/quest/admin/quest=(quest_id)/username=(username)/¶

Fetch user information regarding specific quest.

Example response:

{
    status: "Available",
    current_level: 4,
    user: {
            id: 1
    }
}

POST /api/quest/admin/quest=(quest_id)/username=(username)/¶

Increment current level for specific user and quest.

Example response

{
    current_level: 5,
    user: {
        id: 3,
        username: "toma"
    }
}

Wouso API’s documentation¶

Wouso API-enabled instances¶

Basic information:¶

Notifications¶

Player information¶

Magic and Bazaar¶

Top¶

Races and Groups¶

Messages¶

Games¶

Question of the Day¶

Challenge¶

Quest¶

Indices and tables¶

Table Of Contents

This Page

Navigation

Wouso API’s documentation¶

Wouso API-enabled instances¶

Basic information:¶

Notifications¶

Player information¶

Magic and Bazaar¶

Top¶

Races and Groups¶

Messages¶

Games¶

Question of the Day¶

Challenge¶

Quest¶

Indices and tables¶

Table Of Contents

This Page

Quick search

Navigation