<commit_before>FORMAT: 1A
HOST: https://sandbox-api01.clanofthecloud.com

# ClanOfthecloud APIs

[ClanOfTheCloud](http://www.clanofthecloud.com) is a Mobile Gaming Backend as a Service (Baas) Company. You can create an account on our website, 
and try us with your next social game! We're multiplateform and offer a full API.

## Authentication

Once you've created an account, you can provision a Game in the FrontOffice application in either sandbox or production mode.
We're using a classic APIKEY / APISECRET couple to authenticate all requests.

Every request should have two headers set with your game credentials :

|Header     |               |
|---        |---            |
|x-apikey   |Your API key   |
|x-apisecret|Your API secret|

# Gamers routes 

In addition to the Authentication above, gamers are authenticated too.
Before playing, the gamer needs an identity... Login provides such an identity.


## Login [/v1/gamer/login]

The login route is used for authenticate a gamer

HTTP Basic Authentication is used to authenticate every requests, using the token returned by the request.

|Header     |               |
|---        |---            |
|x-apikey   |Your API key   |
|x-apisecret|Your API secret|
|Authorization| BASIC gamer_id:gamer_secret base64 encoded|

Both `gamer_id` and `gamer_secret` are returned by `/v1/gamer/login`.

It is your responsibility to store these to help the user log in later.

Login for authenticated gamers will one of these : 

* Facebook identity: use the `ID` and the `oauth token` from Facebook

* Google+ identity: use the `ID` and the `oauth token` from Google+

* RAW: use the `gamer_id` and the `gamer_secret` from a previous login

    Note: I've added RAW as a mean to login again, with gamer_id:secret

###### body description

|Field|Description|Value|
|---|---|---|
|network|string, required|can be one of ["raw", "facebook", "googleplus"]
|facebookid|string, required when {network=facebook}| the ID returned by facebook sdk
|facebooktoken|string, required when {network=facebook}| the token returned by facebook sdk
|googleplusid|string, required when {network=googleplus}| the ID returned by google sdk
|googleplustoken|string, required when {network=googleplus}| the token returned by google sdk

    Note: maybe we should use `network, id, token` instead, to remove any ambiguity that login is using a single network...

###### response description
|Field|Description|Value|
|---|---|---|
|gamer_id|string| user_id used in basic authentication for gamer authenticated requests
|gamer_secret|string| secret used in basic authentication for gamer authenticated requests
|profile|json| gamer's profile, including "name", "email", "nickname", ...
|vfs|json| list of key/value associated to the app/game
|gamervfs|json| list of key/value associated to the gamer
|matches|json| array of match currently in open state of the gamer

### Login [POST]

+ Request (application/json)

    + Headers
    
            x-apikey : test_api_key
            x-apisecret : test_api_secret

    + Body
        
            { 
                "network": "facebook",
                "facebookid" : "1000001010",
                "facebooktoken" : "<PASSWORD>"
            }

+ Response 200 (application/json)

        {
            "gamer_token" : "df<PASSWORD>",
            "profile" : {},
            "vfs" : {},
            "gamervfs" : {}
        }

+ Response 401 (application/json)

        {
            "code" : "Unauthorized",
            "message" : "Invalid App Credentials"
        }

### Logout [DELETE]
Logout a gamer

### implementation
* the gamer token has to be deleted on client-side!

+ Request

    + Headers
    
            x-apikey : test_api_key
            x-apisecret : test_api_secret
            Authorization : gamer_id:gamer_secret

+ Response 200 


## Gamer VFS  [/gamer/vfs/{domain}/{key}]

### Get gamer's data [GET]

###### Possible values for error 404
* `Key not found` ... the specified key doesn't exist
* `Domain not found` ... the specified domain doesn't exist

    Note: it should be 404 (resource not found), not 400 (bad request)

###### response description
|Field|Description|Value|
|---|---|---|
|gamervfs|json| list of key/value associated to the gamer

+ Parameters
    + domain (required, string) ... the domain where to retreive the key/value
    + key (optional, string) ... the desired key, if omited all keys of the domains will be returned

+ Request

    + Headers
    
            x-apikey : test_api_key
            x-apisecret : test_api_secret
            Authorization : Basic gamertoken
            
+ Response 200 (application/json)

        {
            "gamervfs" : { "key" :"data which could be a json" }
        }

+ Response 401 (application/json)

        {
            "code" : "Unauthorized",
            "message" : "the gamer token is no longer available, call signin!", 
            "data" : "optional error data" 
        }        

+ Response 404 (application/json)

        {
            "code" : "Key not found",
            "message" : "the specified key is not found"
            "data" : "optional error data" 
        }  

### Set gamer's data [PUT]

**if domain and/or key don't exist, they are created**
<commit_msg>Transferring blueprint from apiary.io<commit_after>FORMAT: 1A
HOST: https://sandbox-api01.clanofthecloud.com

# ClanOfthecloud APIs

[ClanOfTheCloud](http://www.clanofthecloud.com) is a Mobile Gaming Backend as a Service (Baas) Company. You can create an account on our website, 
and try us with your next social game! We're multiplateform and offer a full API.

## Authentication

Once you've created an account, you can provision a Game in the FrontOffice application in either sandbox or production mode.
We're using a classic APIKEY / APISECRET couple to authenticate all requests.

Every request should have two headers set with your game credentials :

|Header     |               |
|---        |---            |
|x-apikey   |Your API key   |
|x-apisecret|Your API secret|

# Gamers routes 

In addition to the Authentication above, gamers are authenticated too.
Before playing, the gamer needs an identity... Login provides such an identity.


## Login [/v1/gamer/login]


The login route is used to authenticate a gamer, and get basic profile information about him.

Login for authenticated gamers will one of these : 

* Facebook identity: use the `ID` and the `oauth token` from Facebook

* Google+ identity: use the `ID` and the `oauth token` from Google+

* RAW: use the `gamer_id` and the `gamer_secret` from a previous login

    Note: I've added RAW as a mean to login again, with gamer_id:secret

After login has been called, HTTP Basic Authentication will be used to authenticate every requests.

|Header     |               |
|---        |---            |
|x-apikey   |Your API key   |
|x-apisecret|Your API secret|
|Authorization| BASIC gamer_id:gamer_secret base64 encoded|

Both `gamer_id` and `gamer_secret` are returned by `/v1/gamer/login`.

It is your responsibility to store these to help the user log in later.


###### body description

A JSON object must be sent in the request body with the following structure.

|Field|Description|Value|
|---|---|---|
|network|string, required|can be one of ["raw", "facebook", "googleplus"]
|id|string, required | the user ID for this network
|token|string, required| the user secret/token for this network

###### response description

The response is a JSON object.

|Field|Description|Value|
|---|---|---|
|gamer_id|string| user_id used in basic authentication for gamer authenticated requests
|gamer_secret|string| secret used in basic authentication for gamer authenticated requests
|profile|json| gamer's profile, including "name", "email", "nickname", ...
|vfs|json| list of key/value associated to the app/game
|gamervfs|json| list of key/value associated to the gamer
|matches|json| array of match currently in open state of the gamer

### Login [POST]

+ Request (application/json)

    + Headers
    
            x-apikey : test_api_key
            x-apisecret : test_api_secret

    + Body
        
            { 
                "network": "facebook",
                "facebookid" : "1000001010",
                "facebooktoken" : "<PASSWORD>"
            }

+ Response 200 (application/json)

        {
            "gamer_token" : "<PASSWORD>",
            "profile" : {},
            "vfs" : {},
            "gamervfs" : {}
        }

+ Response 401 (application/json)

        {
            "code" : "Unauthorized",
            "message" : "Invalid App Credentials"
        }

## Logout [/v1/gamer/logout]

Log a gamer out

### implementation
* the gamer token has to be deleted on client-side!

+ Request

    + Headers
    
            x-apikey : test_api_key
            x-apisecret : test_api_secret
            Authorization : gamer_id:gamer_secret

+ Response 200 

+ Response 401

        {
            "code" : "Unauthorized",
            "message" : "Invalid Gamer Credentials"
        }
        
+ Response 401 (application/json)

        {
            "code" : "Unauthorized",
            "message" : "Invalid App Credentials"
        }

## Gamer VFS  [/v1/gamer/vfs/{domain}/{key}]

### Get gamer's data [GET]

###### Possible values for error 404
* `Key not found` ... the specified key doesn't exist
* `Domain not found` ... the specified domain doesn't exist

###### response description
|Field|Description|Value|
|---|---|---|
|gamervfs|json| list of key/value associated to the gamer

+ Parameters
    + domain (required, string) ... the domain where to retreive the key/value
    + key (optional, string) ... the desired key, if omited all keys of the domains will be returned

+ Request

    + Headers
    
            x-apikey : test_api_key
            x-apisecret : test_api_secret
            Authorization : Basic gamertoken
            
+ Response 200 (application/json)

        {
            "gamervfs" : { "key" :"data which could be a json" }
        }

+ Response 401 (application/json)

        {
            "code" : "Unauthorized",
            "message" : "the gamer token is no longer available, call login again!", 
            "data" : "optional error data" 
        }        

+ Response 404 (application/json)

        {
            "code" : "Key not found",
            "message" : "the specified key is not found"
            "data" : "optional error data" 
        }  

### Set gamer's data [PUT]

**if domain and/or key don't exist, they are created**

{'fraction_non_alphanumeric': 0.10327790973871734, 'fraction_numerical': 0.00855106888361045, 'mean_word_length': 2.6221610461114935, 'pattern_counts': {'":': 2, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '44566', 'n_tokens_mistral': 3168, 'n_tokens_neox': 2975, 'n_words': 1120}