API REST V1.0 Alpha

The API of the gamification plateform is described here.

Note: Arguments marked with a* are not mandatory

#Admin Side

Game Engine

Create game engine

Allows an administrator to create a new game engine.
For that, the administrator has to specifie a name and a description corresponding to his application, and the api will associate an id with it.

POST /admin/game_engine

Values send:

{
     "name": "",
     "description": ""
}

Values received : Request 201 Create, Request 404 Not Found or Request 500 Internal Server Error

//Location: /admin/game_engine/{app-id}

{
     "id": "",
     "name": "",
     "description": "",
     "APIKey": "",
     "secureKey": ""
}

---

Get information about game engine

Allows the administrators to see the information of the existing game engine, corresponding to {app-id}.

GET /admin/game_engine/{app-id}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "app-id": "",
     "name": "",
     "description": "",
     "APIKey": "",
     "secureKey": ""
}

---

Update information about game engine

Allows an administrator to update an existing game engine.

PUT /admin/game_engine/{app-id}

Values send:

{
     "name": "",
     "description": ""
}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "app-id": "",
     "name": "",
     "description": "",
     "APIKey": "",
     "secureKey": ""
}

---

Delete game engine

Allows the administrator to delete the existing game engine, corresponding to {id}.
In return he gets a value depending on the success or not of the delete.

DELETE /admin/{app-id}/game_engine/

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{

}

---

Manage badges

Create a new badge

Allows the administrator to create a new badge.
For that, the administrator has to specifie a name, a description and the URL corresponding to the wished badge, and the api will associate and return an id.

POST /admin/{app-id}/badge

Values send:

{
     "name": "",
     "description": "",
     "URLBadge": "",
     "points"*: <integer> // if mandatory, indicates the number of points that a user can reach to obtain the badge
}

Values received : Request 201 Create, Request 404 Not Found or Request 500 Internal Server Error

//Location: /admin/{app-id}/badge/{id}

{
     "id": {id}, 
     "name": "",
     "description": "",
     "URLBadge": "",
     "points"*: <integer>
}

---

Get information about a badge

Allows the administrator to see the information relative to the badge {id}

GET /admin/{app-id}/badge/{id}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "id": {id}, 
     "name": "",
     "description": "",
     "URLBadge": "",
     "points"*: <integer>
}

---

Update a badge

Allows the administrator to update a new badge.

PUT /admin/{app-id}/badge/{id}

Values send:

{
     "name": "",
     "description": "",
     "URLBadge": "",
     "points"*: <integer>
}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "id": {id}, 
     "name": "",
     "description": "",
     "URLBadge": "",
     "points"*: <integer>
}

---

Delete a badge

DELETE /admin/{app-id}/badge/{id}

Allows the administrator to delete the existing badge, corresponding to {id}. In return he gets a value depending on the success or not of the delete.

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{

}

---

Obtain the list of badges

Allows the administrator to view the full list of existing badges.

GET /admin/{app-id}/badges

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "badges": [{
          "id": {id},
          "name": "",
          "description": "",
          "URLBadge": "",
          "points"*: <integer>
     }]
}

Manage levels

Create a level

Allows the administrator to create a new level.
For that, the administrator has to specified a name, and a value, then the api will associate and return an id.
Each level is associated with a value : points, the user earns a new level when he gets this amounts of points.

POST /admin/{app-id}/level

Values send:

{
     "name": "",
     "description": "",
     "points": ""
}

Values received : Request 201 Create, Request 404 Not Found or Request 500 Internal Server Error

//Location: /admin/{app-id}/level/{id}

{
     "id": {id},
     "name": "",
     "description": "",
     "points": ""
}

---

Get information about a level

GET /admin/{app-id}/level/{id}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "id": {id},
     "name": "",
     "description": "",
     "points": ""
}

---

Update a level

Allows the administrator the name, description or points from the level {id}

PUT /admin/{app-id}/level/{id}

Values send:

{
     "name": "",
     "description": "",
     "points": ""
}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "id": {id},
     "name": "",
     "description": "",
     "points": ""
}

---

Delete a level

Allows the administrator to delete the existing badge, corresponding to {id}. In return he gets a value depending on the success or not of the delete.

DELETE /admin/{app-id}/level/{id}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{

}

---

Obtain the list of levels

Allows the administrator to view the full list of existing badges.

GET /admin/{app-id}/levels

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "levels": [{
          "id": {id},
          "name": "",
          "description": "",
          "points": ""
     }]
}

Manage events

Create a new event

Allows the administrator to create a new level.
For that, the administrator has to specified a name, a description, an event-id which corresponds to the id of the level or badge associated, an event-type : badge or point and a value : a number if event-type is points, otherwise the badge-id, then the api will associate and return an id of the created event, the name, the type, the level or badge id and the value.

POST /admin/{app-id}/event

Values send:

{
     "name": "",
     "description": "",
     "eventId": "",
     "eventType": ("badge" || "point"),
     "value": "" //if event-type is "badge" value is the badge-id, if event type is "point" value is the number of point for the event
}

Values received : Request 201 Create, Request 404 Not Found or Request 500 Internal Server Error

//Location: /admin/{app-id}/event/{id}

{
     "id": {id},
     "name": "",
     "description": "",
     "eventId": "",
     "eventType": ("badge" || "point"),
     "value": ""

---

Update an event

Allows the administrator to update the name, type, value, badge or level ID of the event {id}

PUT /admin/{app-id}/event/{id}

Values send:

{
     "name": "",
     "description": "",
     "eventId": "",
     "eventType": ("badge" || "point"),
     "value": ""
}

Values received : Request 204 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "id": {id},
     "name": "",
     "description": "",
     "eventId": "",
     "eventType": ("badge" || "point"),
     "value": ""
}

---

Delete an event

Allows the administrator to delete the event id. Returns a code depending on the success or fail of the request

DELETE /admin/{app-id}/event/{id}

Values received : Request 204 OK, Request 404 Not Found or Request 500 Internal Server Error

{

}

---

Obtain the list of events

Allows to get the list of existing events

GET /admin/{app-id}/events

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     events: [{
          "id": {id},
          "name": "",
          "description": "",
          "eventId": "",
          "eventType": ("badge" || "point"),
          "value": ""
     }]
}

#Application Side

User

Create a new user

POST /app/{app-id}/user

Values send:

{

}

Values received : Request 201 Create, Request 404 Not Found or Request 500 Internal Server Error

//Location: /app/{app-id}/user/{user-id}

{
     "user-id": {id}
     "points": <integer>
}

---

Information about a user

GET /app/{app-id}/user/{user-id}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "id": {user-id},
     "points": <integer>
     "level": {
          "id": {level-id}
          "name": "",
          "description": "",
          "points": <integer>
     }
     "badges":[{
          "id": {badge-id},
          "name": "",
          "description": "",
          "URLBadge": "",
          "points"*: <integer>
     }]
}

---

Delete a user

DELETE /app/{app-id}/user/{user-id}

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{

}

---

Notify an event

POST /app/{app-id}/user/{user-id}/event

Values send:

{
     "eventId": <event-id>
}

Values received : Request 201 Create, Request 404 Not Found or Request 500 Internal Server Error

{
"user" :{
     "id": {user-id},
     "points": <integer>,
     "badges"*:[{ // if the event triggers the obtainting of a badge
          "name": "",
          "description": "",
          "URLBadge": "",
          "points"*: <integer>
     }],
     "level"*:{ // if the event triggers the reaching of a level
          "name": "",
          "description": "",
          "points": ""
     },
}
}

---

leaderboard

general leaderboard
GET /app/{app-id}/leaderboard

Values received : Request 200 OK, Request 404 Not Found or Request 500 Internal Server Error

{
     "name": "",
     "description": "",
     "users": [{
          "id": {user-id},
          "points": <integer>,
          "levels": [{
               "id": {level-id},
               "name": "",
               "description": "",
               "points": <integer>
          }],
          "badges": [{
               "id": {badge-id},
               "name": "",
               "description": "",
               "URLBadge": "",
               "points"*: <integer>
          }]
     }]
}