Metabans API

This article provides specifications for the Metabans API and is written for programmers or those with an understanding of HTTP and JSON. The reader is expected to understand how to use and manipulate [[Wikipedia:Query_string|query strings]].

== Encoding ==

All examples are given in a GET method format which can be appended to http://metabans.com/api to see the effect. It's recommended for most usage that POST be used. Though the below does work, you should take care to urlencode your keys and values within your query string when passing them to metabans via the GET or POST methods.

*'''Text''': ?requests[0][action]=mbo_availability_account_name&requests[0][account_name]=phogue
*'''Encoded''': ?requests%5B0%5D%5Baction%5D=mbo_availability_acco unt_name&requests%5B0%5D%5Baccount_name%5D=phogue

== Authentication ==

Some commands are open and do not require authentication to access. These commands are prefixed with "mbo_" while commands that require authentication with a username/apikey pair are prefixed with "mb_".

The apikey parameter must be salted with a random string generated by the client. The username, salted api key and salt are all sent for authentication.

SHA1("hello" + "0987654321FEDCBA") = "ABCDEF1234567890"

*Examples
**'''GET''': ?username=phogue&apikey=ABCDEF1234567890&salt=hell o
**Notes
***The above "ABCDEF1234567890" is a psuedo apikey and should be replaced with your own apikey.

== Options ==

Options are case-insensitive strings separated by a comma (,).

*Examples
**'''GET''': ?options=mirror,profiler

==== mirror ====

Mirror will reflect back the request within the response. This could be useful for a client to work on events within responses instead of having to store and sync the original request.

==== profiler ====

Profiler will return the time taken per request

==== json ====

Unused but reserved for future use. All responses are, by default, in json.

==== xml ====

Unused but reserved for future use. All responses are, by default, in json.

== Responses ==

Each response may or may not contain the following fields. Each is optional and if it does not appear in the response can be assumed null
*'''request''': Reflected request. See the option [[#mirror]] to have the request sent back in the response
*'''fetch_time''': The profiler result for this isolated response. See the option [[#profiler]] enable the profiler response
*'''error''': Contains the error code and message if there was a problem processing the request
*'''status''': string "OK" if request was successful
*'''data''': Content is dependent on the request

=== Example ===
Note that some of the below values wouldn't appear together (e.g "status":"OK" and "error": { })
{
{
"request":{ // This would be reflected back with ?options=mirror
"action":"mb_something_something_something_dar ksid e",
"game_name":"BF_BC2",
...
"reason":"Family Guy helps me write boring documentation =\\"
},
"status":"OK", // If all is okay
"error":{ // If an error occured
"code":7,
"message":"Request overflow"
},
"data":{ // The data fields returned is dependent on the request made
"is_documentation_cool":false
},
"fetch_time":"0.0032 s" // How long this isolated request took to process. See ?options=profiler
}
}

== Requests ==

A single http request to http://metabans.com/api can contain up to 128 separate api requests. The responses to each api request are cached and reused through out the http request.

*Examples
**'''GET''':
http://metabans.com/api?options=mirror&requests[0][action]=mbo_availability_account_name&requests[0][account_name]=phogue&requests[1][action]=mbo_availability_account_name&requests[1][account_name]=example
[[http://metabans.com/api?options=mirr...ame%5D=example Try It]]
**Output
***[[#JSON]]: {
"responses":[
{
"request":{
"action":"mbo_availability_account_name",
"account_name":"phogue"
},
"status":"OK",
"data":{
"is_available":false,
"is_valid":true,
"is_you":true
}
},
{
"request":{
"action":"mbo_availability_account_name",
"account_name":"example"
},
"status":"OK",
"data":{
"is_available":true,
"is_valid":true,
"is_you":false
}
}
]
}

=== Parameters ===

{|
!Parameter
!Type
!Description
|-
|player_id
|unsigned integer
|An integer based unique player id generated and assigned by Metabans. Note that Metabans shortens its url's by encoding this integer in base62.
|-
|game_name
|string
|See [[Supported_Games]] for a list of the applicable short game codes.
|-
|player_uid
|string
|A unique identifier supplied by the game. See [[Supported_Games]] for advice on finding the unique identifiers per game.
|-
|alternate_uid
|string
|A unique identifier supplied by third party software working in conjunction with the game (Punkbuster, VAC id). See [[Supported_Games]] for advice on finding the unique identifiers per game.
|-
|player_name
|string
|The players name
|-
|player_ip
|string
|The IPv4 address of the player. If the port is appended Metabans will discard it.
|-
|group_name
|string
|This should generally be the games unedited server name if available, otherwise it can be left out or null.
|-
|assessment_type
|string
|
*'''none''': No assessment has been made for the player. Sending this is as good as a unban, unwatch and unprotect.
*'''watch''': The player is being watched
*'''white''': The player is protected
*'''black''': The player is banned
|-
|assessment_length
|integer
|The length of time in seconds that a ban should be enforced. This can be negative which would be the same as having no assessment at all.
|-
|reason
|string, max 200 chars
|A reason for the assessment. Can be any text, but #hashtags are encouraged to allow for easier grouping of ban types.
|-
|account_id
|unsigned integer
|An integer based unique account id generated and assigned by Metabans.
|-
|account_name
|string
|The short name chosen by the account owner to identify themselves.
|-
|phrase
|string
|A short phrase to search for players and accounts
|}

=== Poly Parameters ===

==== Player Identifier ====

When an action is asking for a [[#Player Identifier|Player Identifier]] you may pass either a players [[#Parameters|player_id]], the unique integer identifier assigned by Metabans or a [[#Parameters|game_name]]/[[#Parameters|player_uid]] pair, the same data you would use to sight the player. A [[#Player Identifier|Player Identifier]] parameter can be used in all actions except [[#mb_sight_player|mb_sight_player]] which demands a [[#Parameters|game_name]]/[[#Parameters|player_uid]] pair.

*[[#Parameters|player_id]]
OR
*[[#Parameters|game_name]] AND [[#Parameters|player_uid]]


==== Account Identifier ====

When an action is asking for a [[#Account Identifier|Account Identifier]] you may pass either an [[#Parameters|account_id]], the unique integer identifier assigned by Metabans or a [[#Parameters|account_name]], the short name chosen by the account owner to identify themselves.

*[[#Parameters|account_id]]
OR
*[[#Parameters|account_name]]


==== Assessment Identifier ====

*[[#Parameters|assessment_id]]
OR
*[[#Player Identifier|Player Identifier]] AND [[#Account Identifier|Account Identifier]]

=== Actions ===

==== Private ====

===== mb_sight_player =====

*Parameters
**[[#Parameters|game_name]]
**[[#Parameters|player_uid]]
**[[#Parameters|player_name]]
**[[#Parameters|player_ip]] - optional
**[[#Parameters|group_name]] - optional
**[[#Parameters|alternate_uid]] - optional
*Examples
**'''GET''': http://metabans.com/api?options=mirr...67890&requests[0][action]=mb_sight_player&requests[0][game_name]=BF_BC2&requests[0][player_uid]=ABCDEF1234567890&requests[0][player_name]=example&requests[0][player_ip]=1.1.1.1&requests[0][group_name]=My%20Server
**Output (Given valid credentials)
***[[#JSON]]: {
"responses":[
{
"request":{
"action":"mb_sight_player",
"game_name":"BF_BC2",
"group_name":"My Server",
"player_uid":"ABCDEF1234567890",
"player_name":"example",
"player_ip":"1.1.1.1"
},
"status":"OK",
"data":{
"is_banned":false
}
}
]
}

===== mb_assess_player =====

*Parameters
**[[#Player Identifier|Player Identifier]]
**[[#Parameters|assessment_type]]
**[[#Parameters|assessment_length]] - optional, defaults to 3 months if excluded
**[[#Parameters|reason]] - optional
*Examples
**'''GET''': http://metabans.com/api?options=mirr...67890&requests[0][action]=mb_assess_player&requests[0][game_name]=BF_BC2&requests[0][player_uid]=ABCDEF1234567890&requests[0][assessment_type]=black&requests[0][assessment_length]=3600&requests[0][reason]=Zomg%20he%20wuz%20#hacking
**Output (Given valid credentials)
***[[#JSON]]: {
"responses":[
{
"request":{
"action":"mb_assess_player",
"game_name":"BF_BC2",
"player_uid":"ABCDEF1234567890",
"assessment_type":"white",
"assessment_length":251864069,
"reason":"Cause #heisme",
},
"fetch_time":"0.0201 s",
"status":"OK",
"data":{
"is_watched":false,
"is_whitelisted":true,
"is_blacklisted":false,
"reason":"Cause #heisme",
"assessment_expires":"2019-05-29T02:14:59",
"relative_assessment_expires":"251864069",
"stamp":"2011-06-02T00:32:07",
"relative_stamp":"-1",
"inherited_blacklist":null,
"is_banned":false
}
}
],
"fetch_time":"0.0354 s"
}

===== mb_follow =====

*Parameters
**[[#Account Identifier|Account Identifier]]
**Output (Given valid credentials)
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mb_follow",
"account_id":"6"
},
"fetch_time":"0.0007 s",
"status":"OK",
"data":{
"account_id":"6",
"is_following":true
}
}
],
"fetch_time":"0.0037 s"
}

===== mb_unfollow =====

*Parameters
**[[#Account Identifier|Account Identifier]]
**Output (Given valid credentials)
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mb_unfollow",
"account_id":"6"
},
"fetch_time":"0.0007 s",
"status":"OK",
"data":{
"account_id":"6",
"is_following":false
}
}
],
"fetch_time":"0.0040 s"
}

===== mb_assessment_comment =====

*Parameters
**[[#Assessment Identifier|Assessment Identifier]]
**[[#Parameters|comment]]
**Output (Given valid credentials)
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mb_assessment_comment",
"assessment_id":"1",
"comment":"Your face was an obvious",
"offset":"0"
},
"fetch_time":"0.0058 s",
"status":"OK",
"data":[
{
"account_name":"phogue",
"post_id":"17",
"uid":"2.17",
"stamp":"2011-06-04T23:21:49",
"relative_stamp":"0",
"rating":"0",
"message":"Your face was an obvious"
}
]
}
],
"fetch_time":"0.0082 s"
}


===== mb_player_comment =====

*Parameters
**[[#Player Identifier|Player Identifier]]
**[[#Parameters|comment]]
**Output (Given valid credentials)
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mb_player_comment",
"player_id":"1",
"comment":"Your face is a bring home.",
"offset":"0"
},
"fetch_time":"0.0023 s",
"status":"OK",
"data":[
{
"account_name":"phogue",
"post_id":"18",
"uid":"1.18",
"stamp":"2011-06-04T23:24:51",
"relative_stamp":"0",
"rating":"0",
"message":"Your face is a bring home."
}
]
}
],
"fetch_time":"0.0158 s"
}


===== mb_player_rate =====

*Parameters
**[[#Player Identifier|Player Identifier]]
**[[#Parameters|rating]]
**Output (Given valid credentials)
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mb_player_rate",
"player_id":"1",
"rating":"1"
},
"fetch_time":"0.0018 s",
"status":"OK",
"data":{
"black_listed":"0",
"white_listed":"5",
"rating":"6",
"positive_ratings":"7",
"negative_ratings":"1",
"game_name":"BF_BC2",
"full_game_name":"Battlefield: Bad Company 2"
}
}
],
"fetch_time":"0.0032 s"
}


===== mb_star_comment_rate =====

*Parameters
**[[#Parameters|post_id]]
**[[#Parameters|rating]]
**Output (Given valid credentials)
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mb_star_comment_rate",
"post_id":"1",
"rating":"1"
},
"fetch_time":"0.0023 s",
"status":"OK",
"data":[
{
"account_name":"Siwagod",
"post_id":"1",
"uid":"1.1",
"stamp":"2011-05-29T02:17:01",
"relative_stamp":"-594777",
"rating":"5",
"message":"Bring pizza home."
}
]
}
],
"fetch_time":"0.0038 s"
}



==== Public ====

===== mbo_search =====

*Parameters
**[[#Parameters|phrase]]
**Output
***[[#JSON]]:{
"responses":[
{
"request":{
"action":"mbo_search",
"phrase":"Phog",
"offset":"0"
},
"fetch_time":"0.0049 s",
"status":"OK",
"data":{
"highest_match":0.8,
"lowest_match":0.8,
"matches":[
{
"type":"account",
"player_id":null,
"account_id":"1",
"popular_player_name":null,
"game_name":null,
"full_game_name":null,
"positive_ratings":null,
"negative_ratings":null,
"black_listed":null,
"white_listed":null,
"account_name":"phogue",
"description":"Zaeed, du Idiot, das war nicht die Zeit wert, die das \u00dcbersetzen ben\u00f6tigt hat",
"website":"http:\/\/phogue.net",
"profile_pic_name":"avatar28",
"assessment_type":null,
"is_following":"0",
"uid":"account.1",
"matched_text":"phogue",
"relevance":80
},
{
"type":"player",
"player_id":"1",
"account_id":null,
"popular_player_name":"Phogue",
"game_name":"BF_BC2",
"full_game_name":"Battlefield: Bad Company 2",
"positive_ratings":"6",
"negative_ratings":"1",
"black_listed":"0",
"white_listed":"4",
"account_name":null,
"description":null,
"website":null,
"profile_pic_name":null,
"assessment_type":"white",
"is_following":"0",
"uid":"player.1",
"matched_text":"Phogue",
"relevance":80
}
]
}
}
],
"fetch_time":"0.0076 s"
}


===== mbo_recent_sightings_groups =====

*Parameters
**[[#Account Identifier|Account Identifier]]

===== mbo_feed =====

*Parameters
**[[#Account Identifier|Account Identifier]]

===== mbo_followers =====

*Parameters
**[[#Account Identifier|Account Identifier]]

===== mbo_leaders =====

*Parameters
**[[#Account Identifier|Account Identifier]]

===== mbo_assessments =====

*Parameters
**[[#Account Identifier|Account Identifier]]


===== mbo_player_aliases =====
*Parameters
**[[#Player Identifier|Player Identifier]]

===== mbo_player_locations =====
*Parameters
**[[#Player Identifier|Player Identifier]]

===== mbo_assessment_comments =====
*Parameters
**[[#Assessment Identifier|Assessment Identifier]]

===== mbo_player_comments =====
*Parameters
**[[#Assessment Identifier|Assessment Identifier]]

===== mbo_player_status =====
*Notes
**Discovers a players current status from a specific accounts point of view.
*Parameters
**[[#Player Identifier|Player Identifier]]
**[[#Account Identifier|Account Identifier]]

===== mbo_player_stats =====

*Parameters
**[[#Player Identifier|Player Identifier]]
Created by , 11-01-2012 at 02:36 PM
Last edited by , 11-01-2012 at 02:39 PM
0 Comments, 7,376 Views

Posting Permissions

Posting Permissions
  • You may not create new articles
  • You may not edit articles
  • You may not post comments
  • You may not post attachments
  • You may not edit your comments