# API

Aradena public application API is language independent software with a RESTful API endpoint. API is available in `production` environment that handles real users, real calls and hold real data.

Here is a list of available endpoints:

- **Production**: https://public.aradena.io/

## Requests

The server speaks [JSON](https://en.wikipedia.org/wiki/JSON). It's recommended that every call to the server includes a `Content-Type` header set to `application/json; charset=utf-8;`.

Requests with `POST` or `PUT` method must send data as `application/json` or `multipart/form-data` when files are included in the request body.

$ curl -X 'GET' 'https://public.aradena.io/' \
       -H 'x-api-key: {API_KEY}' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{}'

## Responses

In case of failure, the server responds with `errors` key, which holds a list of error objects.

{
  "errors": [ ... ],
  "message": 'Validation error'
}

Query requests through `GET` method can return status codes `200`, `400`, `401`, `403` or `500`. Mutations through `POST`, `PUT` and `DELETE` can return also codes `201` and `422`. Invalid routes return status code `404`.

- **200**: Success.
- **201**: Successfully created.
- **400**: Invalid resource or resource not found.
- **401**: Unauthenticated access.
- **403**: Unauthorized access.
- **404**: Path not found.
- **422**: Data validation failed.
- **500**: System error.

## Error Handling

Errors include a unique code number and an error message. The code number helps identifying potential problems and points to the exact position in the system.

{
  ...
  "errors": [
    {
      "code": 400000,
      "message": "Invalid path.",
      "path": ""
    }
  ]
}

If you do not include a valid `x-api-key` header you will get a 403 response.

{ "message": "Forbidden" }

## Authentication

Most of the API routes restrict public access and require authentication. Authenticated requests must include an HTTP header `x-api-key` holding the [API key](https://en.wikipedia.org/wiki/Application_programming_interface_key).

# Routes

We have `public routes` and `private` routes which means that API key is required.

## [private] GET /users/:walletAddress/nfts/:type

> Gets information regarding user nfts based by its [type](#nft-type). Since we have multiple different NFT collections the query parameters and response can be different based on the types.

### Path parameters

| Name | Description |
| ------------- | -------------------------------------------------------------------------------------- |
| walletAddress | [required] A `string` representing the users wallet address. |
| type | [required] An `integer` that presents items only with specified [nft type](#nft-type). |

### Type 1 and 2

> Male and woman warriors

#### Query parameters

| Name | Description |
| -------- | ---------------------------------------------------------------------------------------- |
| offset | An `integer` that defines the number of items to be skipped. Defaults to `0`. |
| limit | An `integer` representing the maximum number of items. Defaults to `25`. |
| locked | A `boolean` that present only nfts that are locked (staked through elder gateway) or not. |
| on_quest | A `boolean` that present only items that are on quest or not. |
| sort | An `integer` that defines sort strategy. |

#### Sort strategies

| Number | Description |
| ------ | ------------------------------------------------- |
| 0 | Sort by `number` ascending order (default). |
| 1 | Sort by `number` in descending order. |

#### Response

- items

| Name | Description |
| -------- | ---------------------------------------------------------------------------------- |
| number | An `integer` representing unique identifier of the nft. |
| type | An `integer` that represents [nft type enum](#nft-type). |
| locked | A `boolean` representing the staked state (if passed through elder gateway or not). |
| on_quest | A `boolean` representing if the nft is used on a quest. |

- total

A `number` count of all data matching the query.

#### Example

{
  "items": [
    { "number": 1, "locked": true, "on_quest": false },
    { "number": 2, "locked": true, "on_quest": true },
    { "number": 4, "locked": true, "on_quest": true },
    { "number": 5, "locked": false, "on_quest": true }
  ],
  "total": 4
}

### Type 3

> Comics

#### Query parameters

| Name | Description |
| -------- | -------------------------------------------------------------------------- |
| offset | An `integer` that defines the number of items to be skipped. Defaults to `0`. |
| limit | An `integer` representing the maximum number of items. Defaults to `25`. |
| on_quest | A `boolean` that present only items that are on quest or not. |
| sort | An `integer` that defines sort strategy. |

#### Sort strategies

| Number | Description |
| ------ | ------------------------------------------------- |
| 0 | Sort by `number` ascending order (default). |
| 1 | Sort by `number` in descending order. |

#### Response

- items

| Name | Description |
| -------- | -------------------------------------------------------- |
| number | An `integer` representing unique identifier of the nft. |
| type | An `integer` that represents [nft type enum](#nft-type). |
| on_quest | A `boolean` representing if the nft is used on a quest. |

- total

A `number` count of all data matching the query.

#### Example

{
  "items": [
    { "number": 1, "on_quest": false },
    { "number": 2, "on_quest": true }
  ],
  "total": 2
}

## [private] GET /quests

> Gets information about currently active quests.

### Query parameters

| Name | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| offset | An `integer` that defines the number of items to be skipped. Defaults to `0`. |
| limit | An `integer` representing the maximum number of items. Defaults to `25`. |
| type | An `integer` that present only items quests a specific [quest type enum](#quest-type). |
| subtype | An `integer` that present only items quests a specific [quest subtype enum](#quest-subtype). |
| sort | An `integer` that defines sort strategy. |
| questPropertyBonusType | An `integer` that present only quests that get bonuses from a specific [quest property bonus enum](#quest-property-bonus-type). Note that `questPropertyBonusType` and `questPropertyBonusWarriorType` form a unique pair. |
| questPropertyBonusWarriorType | An `integer` that present only quests that get bonuses from a specific [quest property bonus warrior enum](#quest-property-bonus-warrior-type). Note that `questPropertyBonusType` and `questPropertyBonusWarriorType` form a unique pair. |

#### Sort strategies

| Number | Description |
| ------ | ----------------------------------------- |
| 0 | Sort by `id` ascending order. |
| 1 | Sort by `id` in descending order. |
| 2 | Sort by `difficulty` in ascending order. |
| 3 | Sort by `difficulty` in descending order. |

### Response

- items

| Name | Description |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| id | An `integer` representing unique identifier of the quest. |
| name | A `string` representing the quest name. |
| description | A `string` representing the quest description. |
| type | An `integer` representing the [quest type enum](#quest-type). |
| subtype | An `integer` representing the [quest subtype enum](#quest-subtype). |
| duration | An `integer` representing the quest duration in hours. |
| difficulty | An `integer` representing the difficulty of the quest ranging from 1 - 10. |
| active_from | A `date` representing if the nft is used on a quest. |
| active_to | A `date` representing if the nft is used on a quest. |
| quest_property_bonus[].name | A `string` representing property name. |
| quest_property_bonus[].type | A `string` representing the [property type enum](#quest-property-bonus-type). |
| quest_property_bonus[].gold_bonus | An `integer` representing gold bonus that the property gives (0.1 = 10%) |
| quest_property_bonus[].warrior_type | An `integer` representing the [property warrior type enum](#quest-property-bonus-warrior-type) that is the receiver of this bonus. |
| quest_property_bonus[].property_group | An `integer` representing the [property enum](#quest-property) that is the receiver of this bonus. |
| quest_property_bonus[].success_bonus | An `integer` representing the bonus for quest success (0.1 = 10%). |
| quest_property_bonus[].duration_bonus | An `integer` representing duration reduction bonus (0.1 = 10%). |
| quest_property_bonus[].experience_bonus | An `integer` representing a bonus in experience for quest (0.1 = 10%). |
| quest_requirements[].type | An `integer` representing the [quest requirement type enum](#quest-requirement-type) |
| quest_requirements[].value | An `integer` representing the minimum required value (inclusive) for the type. |
| quest_rewards[].type | An `integer` representing the [quest reward type enum](#quest-reward-type). |
| quest_rewards[].value | An `integer` representing either base value or from value depending on the type. |
| quest_rewards[].percent | An `integer` representing +/- deviation from base value or null depending on type. |
| quest_rewards[].value_to | An `integer` representing to value or null depending on type. |

- total

A `number` count of all data matching the query.

#### Example

{
  "items": [
    {
      "id": 178,
      "name": "repudiandae ut",
      "type": 2,
      "subtype": null,
      "difficulty": null,
      "description": "Ab consequatur neque est nostrum et at tempora sunt.",
      "duration": 24,
      "gold_multiplier": 2.06,
      "experience_multiplier": 2.52,
      "active_from": null,
      "active_to": null,
      "quest_property_bonus": [
        {
          "name": "No Item",
          "type": 7,
          "gold_bonus": 0.1,
          "warrior_type": 1,
          "success_bonus": null,
          "duration_bonus": 0.1,
          "commodity_bonus": 1,
          "experience_bonus": 0.1
        },
        {
          "name": "Heroic",
          "type": 8,
          "gold_bonus": 0.1,
          "warrior_type": 1,
          "success_bonus": null,
          "duration_bonus": 0.1,
          "commodity_bonus": 1,
          "experience_bonus": 0.1
        },
        {
          "name": "No Item",
          "type": 7,
          "gold_bonus": 0.1,
          "warrior_type": 2,
          "success_bonus": null,
          "duration_bonus": 0.1,
          "experience_bonus": 0.1
        },
        {
          "name": "Heroic",
          "type": 8,
          "gold_bonus": 0.1,
          "warrior_type": 2,
          "success_bonus": null,
          "duration_bonus": 0.1,
          "experience_bonus": 0.1
        }
      ],
      "quest_requirements": [
        {
          "type": 8,
          "value": 20
        }
      ],
      "quest_rewards": [
        {
          "type": 1,
          "value": 10,
          "percent": 0.025,
          "value_to": null
        },
        {
          "type": 3,
          "value": 125,
          "percent": 0.025,
          "value_to": null
        },
        {
          "type": 6,
          "value": 5,
          "percent": 1,
          "value_to": null
        },
        {
          "type": 6,
          "value": 1,
          "percent": 0.5,
          "value_to": null
        }
      ]
    }
  ],
  "total": 1
}

# types

We use multiple enums and types to represent different options. In this section you can find definition for those enums.

## NFT type

| Code | Description |
| ---- | ------------------- |
| 1 | Warriors of Aradena |
| 2 | Woman of Aradena |
| 3 | Aradena Comics |

## Quest type

| Code | Description |
| ---- | ------------- |
| 1 | Towns guard |
| 2 | Beast hunter |
| 3 | Merchant navy |

## Quest subtype

> Each quest type can have a subtype.

### Towns guard

| Code | Description |
| ---- | ----------- |
| 1 | Escort |
| 2 | Public |
| 3 | Brawl |
| 4 | Investigate |
| 5 | Royal |
| 6 | Guard |

### Beast hunter

| Code | Description |
| ---- | ----------- |
| 1 | Studying |
| 2 | Rescue |
| 3 | Hunting |
| 4 | Taming |
| 5 | Scouting |
| 6 | Dungeon |

### Merchant navy

| Code | Description |
| ---- | ----------- |
| 1 | Pirateer |
| 2 | Sea monster |
| 3 | Treasure |
| 4 | Merchants |
| 5 | Storm |
| 6 | Smuggling |

## Quest property bonus type

| Code | Description |
| ---- | ----------- |
| 1 | Background |
| 2 | Weapon |
| 3 | Armour |
| 4 | Headwear |
| 5 | Eyes |
| 6 | Mouth |
| 7 | Front item |
| 8 | Class |

## Quest property bonus warrior type

| Code | Description |
| ---- | ------------------- |
| 1 | Warriors of aradena |
| 2 | Women of Aradena |

## Quest property

| Code | Description |
| ---- | ------------------------------------ |
| 1 | Amber |
| 2 | Amulet Tiara |
| 3 | Archer Cap |
| 4 | Assasin Attire |
| 5 | Assassins Knife |
| 6 | Bald |
| 7 | Ball of Flame |
| 8 | Ball of Ice |
| 9 | Bandanna |
| 10 | Banner Flag |
| 11 | Basket Hilted Sword |
| 12 | Battle Axe |
| 13 | Battle Scarred |
| 14 | Bear Helmet |
| 15 | Beast Hunter Eyes |
| 16 | Black Leather Steel |
| 17 | Black War Paint |
| 18 | Black Wizard Hat |
| 19 | Black Wizardess Hat |
| 20 | Blue Eyes |
| 21 | Blue War Paint |
| 22 | Blue Wizard Eyes |
| 23 | Blue Wizard Robe |
| 24 | Blue Wizardess Robe |
| 25 | Blunt Mace |
| 26 | Bow |
| 27 | Bow and Quiver |
| 28 | Braids |
| 29 | Brown Cloth |
| 30 | Brown Eyes |
| 31 | Brown Wizard Hat |
| 32 | Brown Wizardess Hat |
| 33 | Captains Chainmail |
| 34 | Cat Eyes |
| 35 | Cavalry Helmet |
| 36 | Cavalry Shield |
| 37 | Champagne |
| 38 | Chromed Light Steel Plate |
| 39 | Clean Shaven |
| 40 | Coin Eyes |
| 41 | Common Dress |
| 42 | Common Great Sword |
| 43 | Common Hair |
| 44 | Common Sword |
| 45 | Court Makeup |
| 46 | Crossbow |
| 47 | Crow |
| 48 | Curly |
| 49 | Dames Heavy Steel Plate |
| 50 | Dark Cultist Crown |
| 51 | Dark Dames Crown |
| 52 | Double Swords |
| 53 | Dragon Egg |
| 54 | Dragon Plate Armour |
| 55 | Druid Wizard Staff |
| 56 | Druids Wizard Staff |
| 57 | Druids Wizardess Staff |
| 58 | Dual Colour Pupils |
| 59 | Eagle |
| 60 | Enchanted Amulet Tiara |
| 61 | Enchanted Assasin Attire |
| 62 | Enchanted Bear Helmet |
| 63 | Enchanted Black Leather Steel |
| 64 | Enchanted Black Wizard Hat |
| 65 | Enchanted Black Wizardess Hat |
| 66 | Enchanted Blue Wizard Robe |
| 67 | Enchanted Blue Wizardess Robe |
| 68 | Enchanted Bow |
| 69 | Enchanted Bow and Quiver |
| 70 | Enchanted Brown Wizard Hat |
| 71 | Enchanted Brown Wizardess Hat |
| 72 | Enchanted Captains Chainmail |
| 73 | Enchanted Cavalry Helmet |
| 74 | Enchanted Cavalry Shield |
| 75 | Enchanted Chromed Light Steel Plate |
| 76 | Enchanted Common Sword |
| 77 | Enchanted Dames Heavy Steel Plate |
| 78 | Enchanted Dark Cultist Crown |
| 79 | Enchanted Dark Dames Armour |
| 80 | Enchanted Dark Dames Crown |
| 81 | Enchanted Double Swords |
| 82 | Enchanted Dragon Plate Armour |
| 83 | Enchanted Druid Wizard Staff |
| 84 | Enchanted Druids Wizard Staff |
| 85 | Enchanted Druids Wizardess Staff |
| 86 | Enchanted Executioners Axe |
| 87 | Enchanted Fox Helmet |
| 88 | Enchanted Grand Great Sword |
| 89 | Enchanted Grand Sword |
| 90 | Enchanted Grand Wizard Staff |
| 91 | Enchanted Grand Wizard Staff |
| 92 | Enchanted Grand Wizardess Staff |
| 93 | Enchanted Halberd |
| 94 | Enchanted Heavy Leather |
| 95 | Enchanted Horned Helmet |
| 96 | Enchanted Horse Mane Helmet |
| 97 | Enchanted Improved Sword |
| 98 | Enchanted Infantry Helmet |
| 99 | Enchanted Katana |
| 100 | Enchanted Kings Armour |
| 101 | Enchanted Kings Crown |
| 102 | Enchanted Knights Heavy Steel Plate |
| 103 | Enchanted Leather Shield |
| 104 | Enchanted Light Steel Plate |
| 105 | Enchanted Mace |
| 106 | Enchanted Medium Chainmail |
| 107 | Enchanted Messer |
| 108 | Enchanted Morning Star |
| 109 | Enchanted Pitchfork |
| 110 | Enchanted Prince Crown |
| 111 | Enchanted Princess Crown |
| 112 | Enchanted Purple Wizard Robe |
| 113 | Enchanted Purple Wizardess Robe |
| 114 | Enchanted Queens Armour |
| 115 | Enchanted Queens Crown |
| 116 | Enchanted Queens Guard Armour |
| 117 | Enchanted Ranger Cloak |
| 118 | Enchanted Ranger War Cloak |
| 119 | Enchanted Sabre |
| 120 | Enchanted Sledgehammer |
| 121 | Enchanted Spatha |
| 122 | Enchanted Spear |
| 123 | Enchanted Spell Book |
| 124 | Enchanted Talisman |
| 125 | Enchanted Tankard |
| 126 | Enchanted The Dark Knight Armour |
| 127 | Enchanted The Dark Knights Crown |
| 128 | Enchanted The Kings Guard Armour |
| 129 | Enchanted Trident |
| 130 | Enchanted Used Heavy Steel Plate |
| 131 | Enchanted War Hammer |
| 132 | Enchanted War Horn |
| 133 | Enchanted War Torn Heavy Steel Plate |
| 134 | Enchanted White Wizard Robe |
| 135 | Enchanted White Wizardess Robe |
| 136 | Enchanted Winged Axe |
| 137 | Enchanted Zweihandler |
| 138 | Executioners Axe |
| 139 | Eye Patch |
| 140 | Falchion |
| 141 | Flaming Torch |
| 142 | Fox Helmet |
| 143 | Gold |
| 144 | Gold Coin |
| 145 | Golden Glow |
| 146 | Grand Dress |
| 147 | Grand Great Sword |
| 148 | Grand Sword |
| 149 | Grand Wizard Staff |
| 150 | Grand Wizard Staff |
| 151 | Grand Wizardess Staff |
| 152 | Green Eyes |
| 153 | Grey Eyes |
| 154 | Halberd |
| 155 | Hanger |
| 156 | Heavy Leather |
| 157 | Heroic |
| 158 | Hood |
| 159 | Horned Helmet |
| 160 | Horse Mane Helmet |
| 161 | Improved Sword |
| 162 | Infantry Helmet |
| 163 | Jewelled Mouth Veil |
| 164 | Jian |
| 165 | Katana |
| 166 | Khopesh |
| 167 | Kimono |
| 168 | Kings Armour |
| 169 | Kings Crown |
| 170 | Knights Heavy Steel Plate |
| 171 | Leather Cap |
| 172 | Leather Shield |
| 173 | Legendary |
| 174 | Light Chainmail |
| 175 | Light Leather |
| 176 | Light Steel Plate |
| 177 | Lightning Spell |
| 178 | Long Blonde |
| 179 | Long Coloured |
| 180 | Long Hair |
| 181 | Mace |
| 182 | Magical Tattoos |
| 183 | Mask |
| 184 | Medium Chainmail |
| 185 | Medium Leather |
| 186 | Messer |
| 187 | Mighty |
| 188 | Mohawk |
| 189 | Morning Star |
| 190 | Moustache |
| 191 | Mouth Veil |
| 192 | No Armour |
| 193 | No Item |
| 194 | No Weapon |
| 195 | Nose Piercing |
| 196 | Partisan |
| 197 | Peasant Clothes |
| 198 | Peasant Hair |
| 199 | Peasant Teeth |
| 200 | Pitchfork |
| 201 | Ponytail |
| 202 | Potion |
| 203 | Potion Cork |
| 204 | Priestess Garment |
| 205 | Prince Crown |
| 206 | Princess Crown |
| 207 | Purple Lipstick |
| 208 | Purple Wizard Eyes |
| 209 | Purple Wizard Robe |
| 210 | Purple Wizardess Robe |
| 211 | Queens Armour |
| 212 | Queens Crown |
| 213 | Queens Guard Armour |
| 214 | Rage Eyes |
| 215 | Ranger Cloak |
| 216 | Ranger War Cloak |
| 217 | Red Demon Eyes |
| 218 | Red Dress |
| 219 | Red Lipstick |
| 220 | Refined Beard |
| 221 | Royal Bun |
| 222 | Royal Dress |
| 223 | Royal Robe |
| 224 | Rusted Steel Plate |
| 225 | Sabre |
| 226 | Salmon |
| 227 | Scale Armour |
| 228 | Scar Eye |
| 229 | Scimitar |
| 230 | Severed Head |
| 231 | Shaman Skull |
| 232 | Short Warrior Hair |
| 233 | Shoulder Pad |
| 234 | Silver |
| 235 | Skewered Orc Head |
| 236 | Sky |
| 237 | Slate |
| 238 | Sledgehammer |
| 239 | Smirk |
| 240 | Smoking Pipe |
| 241 | Snake |
| 242 | Spatha |
| 243 | Spear |
| 244 | Spear |
| 245 | Spell Book |
| 246 | Stubble |
| 247 | Talisman |
| 248 | Tan |
| 249 | Tankard |
| 250 | The Dark Dame Armour |
| 251 | The Dark Knight Armour |
| 252 | The Dark Knights Crown |
| 253 | The Kings Guard Armour |
| 254 | Trident |
| 255 | Used Heavy Steel Plate |
| 256 | Vampire Teeth |
| 257 | War Club |
| 258 | War Cry |
| 259 | War Hammer |
| 260 | War Horn |
| 261 | War Scythe |
| 262 | War Torn Heavy Steel Plate |
| 263 | Warrior Beard |
| 264 | White Eyes |
| 265 | White Grand Cloth |
| 266 | White Wizard Robe |
| 267 | White Wizardess Robe |
| 268 | Winged Axe |
| 269 | Wizard Beard |
| 270 | Wooden Sword |
| 271 | Zweihandler |

## Quest requirement type

| Code | Description |
| ---- | -------------- |
| 1 | Silver |
| 2 | Strategy skill |
| 3 | Survival skill |
| 4 | Sailing skill |
| 5 | Rum |
| 6 | Beast blood |
| 7 | Potions |
| 8 | Title |
| 9 | Property |

## Quest reward type

| Code | Description |
| ---- | -------------- |
| 1 | Silver |
| 2 | Strategy skill |
| 3 | Survival skill |
| 4 | Sailing skill |
| 5 | Rum |
| 6 | Beast blood |
| 7 | Potions |