Podium API¶
Healthcheck Routes¶
Healthcheck¶
GET /healthcheck
Validates that the app is still up, including the connection to Redis.
Success Response
Code:
200
Content:
"WORKING"
Error Response
It will return an error if it failed to connect to Redis.
Code:
500
Content:
"<error-details>"
Status Routes¶
Status¶
GET /status
Returns statistics on the health of Podium.
Success Response
Code:
200
Content:
{ "app": { "errorRate": [float] // Exponentially Weighted Moving Average Error Rate }, }
Leaderboard Routes¶
Create or Update a Member Score¶
PUT /l/:leaderboardID/members/:memberPublicID/score
optional query string¶
- prevRank=[true|false]
- if set to true, it will also return the previous rank of the player in the leaderboard, -1 if the player didn’t exist in the leaderboard
- e.g.
PUT /l/:leaderboardID/members/:memberPublicID/score?prevRank=true
- defaults to “false”
- scoreTTL=[integer]
- if set, the score of the player will be expired from the leaderboard past [integer] seconds if it does not update it within this interval
- e.g.
PUT /l/:leaderboardID/members/:memberPublicID/score?scoreTTL=100
- defaults to none (the score will never expire)
Atomically creates a new member within a leaderboard or if member already exists in leaderboard, update their score.
Leaderboard ID should be a valid leaderboard name and memberPublicID should be a unique identifier for the member associated with the score.
Payload
{ "score": [integer] // Integer representing member score }
Success Response
Code:
200
Content:
{ "success": true, "member": { "publicID": [string] // member public id "score": [int] // member updated score "rank": [int] // member current rank in leaderboard "previousRank": [int] // the previous rank of the player in the leaderboard, if requests "expireAt": [int] // unix timestamp of when the score will be expired, if scoreTTL is sent } }
Error Response
It will return an error if an invalid payload is sent or if there are missing parameters.
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Create or Update many Members Score¶
PUT /l/:leaderboardID/scores
optional query string¶
- prevRank=[true|false]
- if set to true, it will also return the previous rank of the player in the leaderboard, -1 if the player didn’t exist in the leaderboard
- e.g.
PUT /l/:leaderboardID/scores?prevRank=true
- defaults to “false”
- scoreTTL=[integer]
- if set, the score of the player will be expired from the leaderboard past [integer] seconds if it does not update it within this interval
- e.g.
PUT /l/:leaderboardID/scores?scoreTTL=100
- defaults to none (the score will never expire)
Atomically creates many new members within a leaderboard or if some members already exists in leaderboard, update their scores.
Leaderboard ID should be a valid leaderboard name and publicID should be a unique identifier for the member associated with the score.
Payload
{ "members": [{ "publicID": [string] // member public id "score": [int], // member updated score }, ...] }
Success Response
Code:
200
Content:
{ "success": true, "members": [{ "publicID": [string] // member public id "score": [int] // member updated score "rank": [int] // member current rank in leaderboard "previousRank": [int] // the previous rank of the player in the leaderboard, if requests "expireAt": [int] // unix timestamp of when the score will be expired, if scoreTTL is sent }, ...] }
Error Response
It will return an error if an invalid payload is sent or if there are missing parameters.
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Increment a Member Score¶
PATCH /l/:leaderboardID/members/:memberPublicID/score
optional query string¶
- scoreTTL=[integer]
- if set, the score of the player will be expired from the leaderboard past [integer] seconds if it does not update it within this interval
- e.g.
PUT /l/:leaderboardID/members/:memberPublicID/score?scoreTTL=100
- defaults to none (the score will never expire)
Atomically creates a new member within a leaderboard with the given increment as score. If member already exists in leaderboard just increment their score.
Leaderboard ID should be a valid leaderboard name and memberPublicID should be a unique identifier for the member associated with the score.
WARNING: Incrementing a member score by 0 is not a valid operation and will return a 400 Bad Request result.
Payload
{ "increment": [integer] // Integer representing increment in member score }
Success Response
Code:
200
Content:
{ "success": true, "member": { "publicID": [string] // member public id "score": [int] // member updated score "rank": [int] // member current rank in leaderboard "expireAt": [int] // unix timestamp of when the score will be expired, if scoreTTL is sent } }
Error Response
It will return an error if an invalid payload is sent or if there are missing parameters.
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Remove a leaderboard¶
DELETE /l/:leaderboardID
Remove the entire leaderboard from Podium.
WARNING: This operation cannot be undone and all the information in the leaderboard will be destroyed.
leaderboardID
should be a valid leaderboard name.
Success Response
Code:
200
Content:
{ "success": true, }
Error Response
Code:
500
Content:
{ "success": false, "reason": [string] }
Get a member score and rank¶
GET /l/:leaderboardID/members/:memberPublicID
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/members/:memberPublicID?order=asc
- defaults to “desc”
- scoreTTL=[true|false]
- if set to true, will return the member’s score expiration unix timestamp
- e.g.
GET /l/:leaderboardID/members/:memberPublicID?scoreTTL=true
- defaults to “false”
Gets a member score and rank within a leaderboard.
Leaderboard ID should be a valid leaderboard name and memberPublicID should be a unique identifier for the desired member.
Success Response
Code:
200
Content:
{ "success": true, "publicID": [string] // member public id "score": [int] // member updated score "rank": [int] // member current rank in leaderboard "expireAt": [int] // unix timestamp of when the member's score will be erased (only if scoreTTL is true) }
Error Response
It will return an error if the member is not found.
Code:
404
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Get multiple member scores and rank¶
GET /l/:leaderboardID/members?ids=publicIDcsv
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/members?ids=publicIDcsv?order=asc
- defaults to “desc”
- scoreTTL=[true|false]
- if set to true, will return the member’s score expiration unix timestamp
- e.g.
GET /l/:leaderboardID/members?ids=publicIDcsv?scoreTTL=true
- defaults to “false”
Gets multiple members’ score and ranks within a leaderboard.
If any public IDs are not found, they will be returned in the notFound
list in the response. This is so a list of all the desired members (i.e.: player’s friends) can be retrieved and only the ones in the leaderboard get returned.
Leaderboard ID should be a valid leaderboard name and publicIDcsv should be a comma-separated list of the desired members Public IDs.
Success Response
Code:
200
Content:
{ "members": [ { "publicID": [string] // member public id "rank": [int] // member rank in the specific leaderboard "position": [int] // member rank for all members returned in this request "score": [int] // member score in the leaderboard "expireAt": [int] // unix timestamp of when the member's score will be erased (only if scoreTTL is true) } ], "notFound": [ "[string]" // list of public ids that were not found in the leaderboard ], "success": true }
Error Response
It will return an error if a list of member ids is not supplied.
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Remove members from leaderboard¶
DELETE /l/:leaderboardID/members?ids=memberPublicID1,memberPublicID2,...
Removes specified members from leaderboard. If a member is not in leaderboard, do nothing.
Leaderboard ID should be a valid leaderboard name and ids should be a list of unique identifier for the members being removed, separated by commas.
Success Response
Code:
200
Content:
{ "success": true, }
Error Response
Code:
500
Content:
{ "success": false, "reason": [string] }
Get a member score and rank in many leaderboards¶
GET /m/:memberPublicID/scores?leaderboardIds=leaderboard1,leaderboard2,...
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /m/:memberPublicID/scores?leaderboardIds=leaderboard1,leaderboard2,...?order=asc
- defaults to “desc”
- scoreTTL=[true|false]
- if set to true, will return the member’s score expiration unix timestamp
- e.g.
GET /m/:memberPublicID/scores?leaderboardIds=leaderboard1,leaderboard2,...?scoreTTL=true
- defaults to “false”
Get a member score and rank within many leaderboards.
Leaderboard Ids should be valid leaderboard names separated by commas.
Sucess Response
Code: 200
Content:
{ "scores": [ { "leaderboardID": "teste", "rank": 1, "score": 100, "expireAt": [int] // unix timestamp of when the member's score will be erased (only if scoreTTL is true) }, { "leaderboardID": "teste2", "rank": 1, "score": 100, "expireAt": [int] // unix timestamp of when the member's score will be erased (only if scoreTTL is true) } ], "success": true }
Error Response
- Code: 500
- Content:
{ "reason": "Could not find data for member teste3 in leaderboard teste3.", "success": false }
Get a member rank¶
GET /l/:leaderboardID/members/:memberPublicID/rank
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/members/:memberPublicID/rank?order=asc
- defaults to “desc”
Gets a member rank within a leaderboard.
Leaderboard ID should be a valid leaderboard name and memberPublicID should be a unique identifier for the desired member.
Success Response
Code:
200
Content:
{ "success": true, "publicID": [string] // member public id "rank": [int], // member current rank in leaderboard }
Error Response
It will return an error if the member is not found.
Code:
404
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Get members around a member¶
GET /l/:leaderboardID/members/:memberPublicID/around?pageSize=10
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/members/:memberPublicID/around?pageSize=10?order=asc
- defaults to “desc”
- getLastIfNotFound=[true|false]
- if set to true, will treat members not in ranking as being in last position
- if set to false, will return 404 when the member is not in the ranking
- e.g.
GET /l/:leaderboardID/members/:memberPublicID/around?getLastIfNotFound=true
- defaults to “false”
Gets a list of members with ranking around that of the specified member within a leaderboard.
The pageSize
querystring parameter specifies the number of members that will be returned from this operation. This means that pageSize/2
members will be above the specified member and the other pageSize/2
will be below.
Podium will compensate if no more members can be found above or below (first or last member in the leaderboard ranking) to ensure that the desired number of members is returned (up to the number of members in the leaderboard).
Leaderboard ID should be a valid leaderboard name and memberPublicID should be a unique identifier for the desired member.
Success Response
Code:
200
Content:
{ "success": true, "members": [ { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, //... ], }
Error Response
It will return an error if the member is not found.
Code:
404
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Get members around a score¶
GET /l/:leaderboardID/scores/:score/around?pageSize=10
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/scores/:score/around?pageSize=10?order=asc
- defaults to “desc”
Gets a list of members with score around that of the specified specified in the request. If the score
parameter falls outside the leaderboard [minScore, maxScore], it will return the bottom/top rank members in the leaderboard, respectively.
The pageSize
querystring parameter specifies the number of members that will be returned from this operation. That means there will be around pageSize/2
(+-1) members with score above the specified score, and pageSize/2
(+-1) with score below.
Podium will compensate if no more members can be found above or below (first or last member in the leaderboard ranking) to ensure that the desired number of members is returned (up to the number of members in the leaderboard).
Leaderboard ID should be a valid leaderboard name and score
should be a valid number.
Success Response
Code:
200
Content:
{ "success": true, "members": [ { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, //... ], }
Error Response
It will return an error if the leaderboard is not found or the request has invalid parameters.
Code:
404
Content:
{ "success": false, "reason": [string] }
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Get the number of members in a leaderboard¶
GET /l/:leaderboardID/members-count/
Gets the number of members in a leaderboard.
Leaderboard ID should be a valid leaderboard name.
Success Response
Code:
200
Content:
{ "success": true, "count": [int], // number of members in leaderboard }
Error Response
Code:
500
Content:
{ "success": false, "reason": [string] }
Get the top N members in a leaderboard (by page)¶
GET /l/:leaderboardID/top/:pageNumber?pageSize=:pageSize
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/top/:pageNumber?pageSize=:pageSize?order=asc
- defaults to “desc”
Gets the top N members in a leaderboard, by page.
leaderboardID
should be a valid leaderboard name, pageNumber
is the current page you are looking for and pageSize
is the number of members per page that will be returned.
This means that if you want the top 20 members, you’ll call /l/my-leaderboard/top/1?pageSize=20
for the first 20, /l/my-leaderboard/top/2?pageSize=20
for members 21-40 and so on.
Success Response
Code:
200
Content:
{ "success": true, "members": [ { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, //... ] }
Error Response
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Get the top x% members in a leaderboard¶
GET /l/:leaderboardID/top-percent/:percentage
optional query string¶
- order=[asc|desc]
- if set to asc, will treat the ranking with ascending scores (less is best)
- e.g.
GET /l/:leaderboardID/top-percent/:percentage?order=asc
- defaults to “desc”
Gets the top x% members in a leaderboard.
leaderboardID
should be a valid leaderboard name, percentage
is the % of members you want to return.
The number of members is bound by the configuration api.maxReturnedMembers
, that defaults to 2000 members.
Success Response
Code:
200
Content:
{ "success": true, "members": [ { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, { "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard }, //... ] }
Error Response
If the percentage is not a valid integer between 1 and 100, you’ll get a 400.
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }
Member Routes¶
Create or update score for a member in several leaderboards¶
PUT /m/:memberPublicID/scores
optional query string¶
- prevRank=[true|false]
- if set to true, it will also return the previous rank of the player in the leaderboard, -1 if the player didn’t exist in the leaderboard
- e.g.
PUT /l/:leaderboardID/members/:memberPublicID/score?prevRank=true
- defaults to “false”
- scoreTTL=[integer]
- if set, the score of the player will be expired from the leaderboards past [integer] seconds if it does not update it within this interval
- e.g.
PUT /l/:leaderboardID/members/:memberPublicID/score?scoreTTL=100
- defaults to none (the score will never expire
Atomically creates a new member within many leaderboard or if member already exists in each leaderboard, updates their score.
memberPublicID
should be a unique identifier for the member associated with the score. Each leaderboardID
should be a valid leaderboard name.
Payload
{ "score": [integer], // Integer representing member score "leaderboards": [array of leaderboardID] // List of all leaderboards to update }
Success Response
Code:
200
Content:
{ "success": true, "scores": [ { "leaderboardID": [string] // leaderboard where this score was set "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard "previousRank": [int] // the previous rank of the player in the leaderboard, if requests }, { "leaderboardID": [string] // leaderboard where this score was set "publicID": [string] // member public id "score": [int], // member updated score "rank": [int], // member current rank in leaderboard "previousRank": [int] // the previous rank of the player in the leaderboard, if requests }, //... ] }
Error Response
It will return an error if an invalid payload is sent or if there are missing parameters.
Code:
400
Content:
{ "success": false, "reason": [string] }
Code:
500
Content:
{ "success": false, "reason": [string] }