TGDSO Transaction & Notfications

TGDSO Transactions & Notifications

TGDSO uses HTTPS POST Method exclusively to send Requests. A Request is expected to receive a specific type of Response from the TGDSO Contests Server. We refer to this Request-Response Pair as a Transaction. A Request that does not require a Response is referred to as a Notification. TGDSO Transactions & Notifications implement the JSON-RPC 2.0 Specification to request services from TGDSO Contests Servers.

JSON-RPC Example:

{“jsonrpc”:”2.0″,
“method”:”Session_INVITE”,
“params”:{
“game_id”:”6e73861fd2d75a76e54b472e609eaf98″,
“user”:”techlordx”,
“pass”:”6e4cd40a1a8c17f191d2118d16a976a7″,
“format”:”TGDSOJSON”
},
“id”: 1}

A Session must be established with TGDSO Contests Servers to receive any services. The Game Application must initiate the process by sending a Invitation Transaction: Session INVITE or User REGISTER. These Transactions provide Authentication Information to establish a Session with TGDSO Contests Servers. Due to implementation of the JSON-RPC 2.0 Specification, the Request Parameters and Response Result contain information specific to the type of Transaction/Notification.

Using an example Session INVITE Transaction below, we’ll explain it’s structure:

Request

JSON-RPCParametersRequiredDatatypeDescription
{"jsonrpc":"2.0",    
"method":"Session_INVITE",   Service Transaction Method.
"params":{    
 "game_id":"6e73861fd2d75a76e54b472e609eaf98",xstringThe ID of your Game Application issued by TheGameDevStore.com.
 "user":"techlordx",xstringThe name of the Game Server or Player.
 "pass":"6e4cd40a1a8c17f191d2118d16a976a7",xstringGame Server (optional) or User Pass Token.
 "format":"TGDSOJSON" stringResponse Output Format. Default JSON.
},    
"id": 1}    

The method is the Service Transaction. Each Service has it own set of Transactions. The parameters passed to RPC are Session Identification Data: game_id and user credentials. Session Identification Data persists as long as a Session is Alive. This data includes:

  • IP (HTTPS Header) is unique identifier for the User-Agent’s Network Connection.
  • Game_Id is unique identifier for the Game Product assigned by TheGameDevStore.com upon Licensing.
  • User Credentials is unique identifier for Multiplayer Server, Single Player, or Team.

Response

If Authentication of the Session INVITE Transaction is successful, the TGDSO Contests Servers will respond with a Signature for use in the next Transaction. See Signature:

JSON-RPCParametersRequiredDatatypeDescription
{"jsonrpc":"2.0",    
"result": {    
 "signature":"3208fde0470719372f8313ddd5884a75"xhashSigned Authentication Token issued by TGDSO Contest Server.
},    
"id": 1}    

Otherwise, if the Authentication fails, the result is an Failure code is in the response:

JSON-RPCParametersRequiredDatatypeDescription
{"jsonrpc":"2.0",    
"result":{    
 "failure":1xintegerFailure Code 1: Authentication Failed. Incorrect Username/Password Combination.
},    
"id": 1}    

TGDSO Contests Server Response will always contain a Signature on success or an Failure Code on failure. Note: RPC Call with Invalid JSON  will receive the applicable JSON-RPC error Responses:

{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}
{"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

Signature

A Signature is a unique Signed Authentication Token issued by TheGameDevStore.com to your Game App for validating all Transactions & Notifications. For performance, TheGameDevStore.com associates multiple pieces of Session identification Data to the Signature, eliminating the need to send Session Identification Data Key/Value pairs to authenticate each Request.

With exception to Initiation Transactions, TGDSO Contests Servers expect a Signature with all Transactions & Notifications. All Transaction Response contain a new Signature for use in the next Transaction/Notification Request. Notifications do not return a new signature leaving Signature reusable.

If TGDSO Contests Servers receive a Transaction with an unexpected Signature, Authentication will fail with an Error Response. Three Failed attempts will result in Session Closure and a new Session INVITE is required. If a Notification is received with an unexpected Signature, the Notification is ignored.

Formats

TGDSO Contests Server can return data in the following formats:

JSON (default)
Returns data as a JSON string.This is the default format if none is requested.
TGDSOJSON (Alphanumeric Keynames w/ Datatype Indicator and No Quotes)
Returns data as a JSON string.
XML
Returns information as XML.
Key|Value Pair
Returns data with each key|value pairs separated by carriage return. This is a simple data format to use if you can’t parse XML or JSON data.
TournamentBlitz (Legacy)
The first API format developed. Returns key/value data separated by carriage return. A symbolic homage to the original TournamentBlitz, NOT for production use.
RAW
This is a generic data format used for certain URL paths to return a chunk of single data.

Submit a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Pin It on Pinterest