not sure if this will help you but it has all the information you need to build a rest API.
================================================== ==============================
OUTSPARK REST API
================================================== ==============================
This document describes the interface to Outspark's REST API system. The scope
of it does not extend to the mechanisms of performing HTTP requests, except to
suggest certian approaches.
Document version: 1.2.0
================================================== ==============================
REST
================================================== ==============================
REST is Representational State Transfer, and is widely used by various systems
to provide interfaces to the external world. REST is based on HTTP protocol.
Much more information can be found here:
Representational state transfer - Wikipedia, the free encyclopedia REST - ????, ?? ??? ????
Outspark's REST platform (ORP) implementation is much more simplified from the
one described in that page. This system responds to GET or POST requests (which
are considered equivalent), and all the operation parameters are specified in
the query part of the request. It should be noted that the platform may be
extended in the future to respond to PUT/DELETE requests as well.
================================================== ==============================
REQUESTS
================================================== ==============================
API requests should be performed as normal HTTP GET requests (similar to
fetching a Web page).
================================================== ==============================
RESPONSE
================================================== ==============================
ORP responds to requests via standard HTTP means by issuing an HTTP status code,
such as 200, 401, etc. These codes are documented in the following URL:
If the HTTP status code is 200 (success), the Content-Type header of the
response will be "application/json". The body of the response will contain
a serialized JSON representation of the results of the operation, which is
currently always an associative array. An example of such response is:
{"token_age":"5","user_id":"7589","login":"aardvar d"}}
The JSON can be parsed in a number of ways. Please see the following URL for the
appropriate resource:
If the HTTP status code is not 200 (error), the Content-Type header of the
response will be "application/xml". The body of the response will contain an XML
document describing the problem. An example of such document is:
<?xml version="1.0" encoding="utf-8"?>
<Error xmlns="http://rest.outspark.net/">
<handler-class>UserLoginResource</handler-class>
<code>401</code>
<message>Unauthorized access</message>
<request>
<method>GET</method>
<uri><![CDATA[http://192.168.30.20/user/v1/login]]></uri>
</request>
</Error>
The XML can be parsed via whatever means are available to the developer.
================================================== ==============================
SIGNED REQUESTS
================================================== ==============================
Certain API calls in ORP are required to contain a signature parameter, in order
to verify the authenticity of the requesting entity. The signature is based on
SHA-256 algorithm and uses a shared secret. This secret is generated by Outspark
for each developer and is communicated to them in a secure fashion. To generate
a signature, use the following procedure:
1. Take the URI portion of the request. For example, if the desired request is:
the URI portion will be everything after the domain, that is:
/user/v1/getUserInfo?realm=fiesta&token=xhha834oho2384t6
2. Append the shared secret after the URI. For example, if the shared secret is
"our_shared_secret", then the result would be:
/user/v1/getUserInfo?realm=fiesta&token=xhha834oho2384t6our sharedsecret
3. Run this string through SHA-256 hashing algorithm. The result will be a hash.
4. Take the hash and append it as a 'sig' parameter to the desired request. For
example, if the hash is "888189abfc86496812986", the resulting request URL
will be:
SHA-256 algorithm is described here:
SHA-2 - Wikipedia, the free encyclopedia
There are a number of libraries in just about any programming language that
provide implementation of this algorithm.
================================================== ==============================
VERSIONING
================================================== ==============================
Each API resource is versioned. It is required to append a version number after
the resource name. For example, to invoke version 1 of the /user resource, the
request would start with /user/v1/, followed by the desired function.
================================================== ==============================
API INTERFACE
================================================== ==============================
/user resource
~~~~~~~~~~~~~~
This resource is responsible for performing user (game player) related
operations. Currently available operations are:
/login
------
Verifies user's authentication and returns a login token to be used for
obtaining further information about the user. Usually passed to the game
client.
Parameters:
realm identifier of the game the user should be logged into
user Outspark username of the user
password MD5 hash of the user's password
version current version of the game that the user has installed
Response:
token login token
Signature required:
no
/getUserInfo
------------
Returns additional information about the user, based on the login token.
Parameters:
realm identifier of the game the user is logged into
token login token generated by /login function
Response:
token_age the age of the login token (in minutes)
user_id numeric identifier of the user
login username of the user
user_role role of the user: "gm" or "user"
blocked boolean specifying whether the user is blocked from the game
Signature required:
yes
/giveInfraction
---------------
Notify Outspark of in-game user infractions.
Parameters:
realm identifier of the game the user is logged into
outsparkID numeric identifier of the Outspark user
characterID alphanumeric identifier of the characterID
worldID numeric identifier of the game worldID (0 if NA)
level numeric identifier of the infraction level
Response:
result boolean flag indicating whether item status change succeeded
or not
Signature required:
yes
/getSparkCashBalance
--------------------
Returns a user's available SparkCash balance
Parameters:
userID numeric identifier of the Outspark user
Response:
balance the user's available SparkCash balance
/store resource
~~~~~~~~~~~~~~~
This resource is responsible for performing Outspark Store related operations.
Currently available operations are:
/getPurchasedItems
------------------
Returns a list of items purchased by the user.
Parameters:
realm identifier of the game for which the items are purchased
outsparkID numeric identifier of the Outspark user
Response:
items List of arrays representing information about each item
Each array contains the following fields:
orderItemID unique identifier of the purchased item, per-order
(generated by Outspark)
gameItemID unique identifier of the item, generated by the developer
orderTime timestamp of the order (Unix timestamp)
quantity quantity of the given item in the order
isUsed whether the item has already been used in the game
Signature required:
yes
/setItemUsed
------------
Flags the item as having been used (placed into inventory) in the game.
Parameters:
realm identifier of the game for which the items are purchased
outsparkID numeric identifier of the Outspark user
worlID numeric identifier of the game world
characterID numeric identifier of the user's character in the game
orderItemID identifier of the item (from /getPurchasedItems call)
Response:
result boolean flag indicating whether item status change succeeded
or not
Signature required:
yes
/setItemActivated
-----------------
Flags the item as having been activated (lease timer started) in the game.
Parameters:
realm identifier of the game for which the items are purchased
outsparkID numeric identifier of the Outspark user
worlID numeric identifier of the game world
characterID numeric identifier of the user's character in the game
orderItemID identifier of the item (from /getPurchasedItems call)
Response:
result boolean flag indicating whether item status change succeeded
or not
Signature required:
yes
/purchaseItem
-------------
Performs a premium item purchase.
Parameters:
realm identifier of the game for which the items are purchased
userID numeric identifier of the Outspark user
oskItemID numeric in-game identifier for the premium item
Response:
result "success" or "failed"
value on success value will contain the transaction UUID for the
purchase
Signature required:
yes
--------------------------------------------------------------------------------
TBD
/avatarium
~~~~~~~~~~
/gamestatus/update
* userID numeric identifier of the Outspark user
* gameHandle short game handle ("fiesta", "sos", etc)
* action game action: "login" or "logout"
/character/add
* userID numeric identifier of the Outspark user
* gameHandle short game handle (alphanumeric, "fiesta", "sos", etc)
* worldID world index (numeric, starting from 0)
* charName character name (alphanumeric)
* charLevel character level (optional)
* charClass character class (alphanumeric, optional)
/character/update
* userID numeric identifier of the Outspark user
* gameHandle short game handle (alphanumeric, "fiesta", "sos", etc)
* worldID world index (numeric, starting from 0)
* charName character name (alphanumeric)
* charLevel character level (optional)
* charClass character class (alphanumeric, optional)
/character/delete
* userID numeric identifier of the Outspark user
* gameHandle short game handle (alphanumeric, "fiesta", "sos", etc)
* worldID world index (numeric, starting from 0)
* charName character name (alphanumeric)
================================================== ==============================
REQUEST EXAMPLES
================================================== ==============================
Obtain information about the user based on a login token:
Obtain list of purchased items:
Flag item as used:
/* vim: set et ts=4 tw=80 sw=2: */
