================================================================================
 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:

   http://en.wikipedia.org/wiki/Representational_State_Transfer
   http://ko.wikipedia.org/wiki/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:

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

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":"aardvard"}}

The JSON can be parsed in a number of ways. Please see the following URL for the
appropriate resource:

    http://json.org/

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:

   http://rest.outspark.net/user/v1/getUserInfo?realm=fiesta&token=xhha834oho2384t6

   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=xhha834oho2384t6oursharedsecret

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:

   http://rest.outspark.net/user/v1/getUserInfo?realm=fiesta&token=xhha834oho2384t6&sig=888189abfc86496812986

SHA-256 algorithm is described here:

    http://en.wikipedia.org/wiki/SHA-256

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:

    http://rest.outspark.net/user/v1/login?realm=fiesta&token=38sdfnlsdf87&sig=8863cab7467bfca868

Obtain list of purchased items:

    http://rest.outspark.net/user/v1/getPurchasedItems?realm=fiesta&outsparkID=78647&sig=8863cab7467bfca868

Flag item as used:

    http://rest.outspark.net/user/v1/getPurchasedItems?realm=fiesta&outsparkID=78647&worldID=0&characterID=7475&orderItemID=12999&sig=8863cab7467bfca868


/* vim: set et ts=4 tw=80 sw=2: */
