solidus_api_v2 0.2.0

data/docs/source/fonts/slate.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" >
+<svg xmlns="http://www.w3.org/2000/svg">
+<metadata>Generated by IcoMoon</metadata>
+<defs>
+<font id="slate" horiz-adv-x="1024">
+<font-face units-per-em="1024" ascent="960" descent="-64" />
+<missing-glyph horiz-adv-x="1024" />
+<glyph unicode="&#x20;" d="" horiz-adv-x="512" />
+<glyph unicode="&#xe600;" d="M438.857 877.714q119.429 0 220.286-58.857t159.714-159.714 58.857-220.286-58.857-220.286-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857zM512 165.143v108.571q0 8-5.143 13.429t-12.571 5.429h-109.714q-7.429 0-13.143-5.714t-5.714-13.143v-108.571q0-7.429 5.714-13.143t13.143-5.714h109.714q7.429 0 12.571 5.429t5.143 13.429zM510.857 361.714l10.286 354.857q0 6.857-5.714 10.286-5.714 4.571-13.714 4.571h-125.714q-8 0-13.714-4.571-5.714-3.429-5.714-10.286l9.714-354.857q0-5.714 5.714-10t13.714-4.286h105.714q8 0 13.429 4.286t6 10z" />
+<glyph unicode="&#xe602;" d="M585.143 164.571v91.429q0 8-5.143 13.143t-13.143 5.143h-54.857v292.571q0 8-5.143 13.143t-13.143 5.143h-182.857q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h54.857v-182.857h-54.857q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h256q8 0 13.143 5.143t5.143 13.143zM512 676.571v91.429q0 8-5.143 13.143t-13.143 5.143h-109.714q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h109.714q8 0 13.143 5.143t5.143 13.143zM877.714 438.857q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" />
+<glyph unicode="&#xe606;" d="M733.714 531.428q0 16-10.286 26.286l-52 51.429q-10.857 10.857-25.714 10.857t-25.714-10.857l-233.143-232.571-129.143 129.143q-10.857 10.857-25.714 10.857t-25.714-10.857l-52-51.429q-10.286-10.286-10.286-26.286 0-15.429 10.286-25.714l206.857-206.857q10.857-10.857 25.714-10.857 15.429 0 26.286 10.857l310.286 310.286q10.286 10.286 10.286 25.714zM877.714 438.857q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" />
+<glyph unicode="&#xe607;" d="M658.286 475.428q0 105.714-75.143 180.857t-180.857 75.143-180.857-75.143-75.143-180.857 75.143-180.857 180.857-75.143 180.857 75.143 75.143 180.857zM950.857 0q0-29.714-21.714-51.429t-51.429-21.714q-30.857 0-51.429 21.714l-196 195.429q-102.286-70.857-228-70.857-81.714 0-156.286 31.714t-128.571 85.714-85.714 128.571-31.714 156.286 31.714 156.286 85.714 128.571 128.571 85.714 156.286 31.714 156.286-31.714 128.571-85.714 85.714-128.571 31.714-156.286q0-125.714-70.857-228l196-196q21.143-21.143 21.143-51.429z" horiz-adv-x="951" />
+</font></defs></svg>

data/docs/source/includes/_authentication.md

@@ -0,0 +1,61 @@
+# Authentication
+
+```shell
+# Specifying the token as a header.
+curl "https://kabuni.com/api/v1/endpoint"
+  -H "X-Spree-Token: abc123"
+
+# Specifying the token as a param.
+curl "/api/v1/endpoint"
+  -d token=abc123
+```
+
+> Make sure to replace `abc123` with your API key.
+
+Spree uses API keys to allow access to the API.
+To obtain a token, you must either create a new user, or, via token authentication, "log" the user in.
+
+Spree does not expect every request to require an API key (such as reading public product data).
+
+## Authenticate a User (Login)
+
+```shell
+curl "https://kabuni.com/api/v1/account/signin"
+  -X POST
+  -d user[email]=spree@example.com
+  -d user[password]=spree123
+```
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "spree_users",
+    "attributes": {
+      "email": "spree@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "job_title": null,
+      "based_city": null,
+      "experience": null,
+      "avatar": "default/avatar-placeholder.jpg",
+      "role": "user",
+      "biography": null,
+      "client_budget": null,
+      "license_number": null,
+      "certification_authority": null,
+      "is_newsletter_subscribed": null,
+      "is_designer_available": true
+    },
+    "relationships": {
+      "store": {
+        "data": null
+      }
+    }
+  }
+}
+```
+
+To login users, you will need to supply the `email` and `password`.
+The response will be a user data object with the token in the body.
+The response's headers will include a `X-Spree-Token` which is what you will use as the token.

data/docs/source/includes/_countries.md

@@ -0,0 +1,133 @@
+# Countries
+
+## List Countries
+
+```shell
+curl "https://kabuni.com/api/v2/countries"
+```
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "spree_countries",
+      "attributes": {
+        "iso_name": "ANDORRA",
+        "iso": "AD",
+        "iso3": "AND",
+        "name": "Andorra",
+        "numcode": 20,
+        "states_required": true
+      },
+      "relationships": {
+        "states": {
+          "data": [
+            {
+              "type": "spree_states",
+              "id": "1"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+List all of the ~200 countries in the DB.
+
+## Show Country
+
+```shell
+curl "https://kabuni.com/api/v2/countries/1"
+```
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "spree_countries",
+    "attributes": {
+      "iso_name": "ANDORRA",
+      "iso": "AD",
+      "iso3": "AND",
+      "name": "Andorra",
+      "numcode": 20,
+      "states_required": true
+    },
+    "relationships": {
+      "states": {
+        "data": [
+          {
+            "type": "spree_states",
+            "id": "1"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Select a country via its `id`.
+
+## List States of a Country
+
+```shell
+curl "https://kabuni.com/api/v2/countries/1/states"
+```
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "spree_states",
+      "attributes": {
+        "name": "Canillo",
+        "abbr": "02"
+      },
+      "relationships": {
+        "country": {
+          "data": {
+            "type": "spree_countries",
+            "id": "1"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+See all of the states that a country owns via the country's `id`.
+
+## Show State of a Country
+
+```shell
+curl "https://kabuni.com/api/v2/countries/1/states/1"
+```
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "spree_states",
+    "attributes": {
+      "name": "Canillo",
+      "abbr": "02"
+    },
+    "relationships": {
+      "country": {
+        "data": {
+          "type": "spree_countries",
+          "id": "1"
+        }
+      }
+    }
+  }
+}
+```
+
+View one of the states that a country owns via the country's `id` and the state's `id`.

data/docs/source/includes/_errors.md

@@ -0,0 +1,17 @@
+# Errors
+
+The Spree API uses the following error codes:
+
+Error Code | Meaning
+---------- | -------
+400 | Bad Request -- Your request sucks
+401 | Unauthorized -- Your API key is wrong
+403 | Forbidden -- The kitten requested is hidden for administrators only
+404 | Not Found -- The specified kitten could not be found
+405 | Method Not Allowed -- You tried to access a kitten with an invalid method
+406 | Not Acceptable -- You requested a format that isn't json
+410 | Gone -- The kitten requested has been removed from our servers
+418 | I'm a teapot
+429 | Too Many Requests -- You're requesting too many kittens! Slow down!
+500 | Internal Server Error -- We had a problem with our server. Try again later.
+503 | Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

data/docs/source/includes/_filtering.md

@@ -0,0 +1,11 @@
+# Filtering
+
+```shell
+curl "https://kabuni.com/api/v2/kittens?filter[id]=1"
+curl "https://kabuni.com/api/v2/kittens?filter[id]=2,3,4"
+curl "https://kabuni.com/api/v2/kittens?filter[breed]=Persian,British%20Shorthair,Bengal"
+```
+
+This project supports the [JSON API's `filter` keyword](http://jsonapi.org/format/#fetching-filtering) with only the root object, not any of its relationships yet.
+You can filter any of the attributes that is inside of the data object.
+Please see the example requests to the side on how you my filter a kitten object.

data/docs/source/includes/_images.md

@@ -0,0 +1,201 @@
+# Images
+
+## List Images
+
+```shell
+curl "https://kabuni.com/api/v2/images"
+```
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "spree_images",
+      "attributes": {
+        "position": 1,
+        "alt": null,
+        "links": {
+          "original": "/spree/products/1/original/ror_baseball_jersey_red.png?1442035822",
+          "mini": "/spree/products/1/mini/ror_baseball_jersey_red.png?1442035822",
+          "small": "/spree/products/1/small/ror_baseball_jersey_red.png?1442035822",
+          "product": "/spree/products/1/product/ror_baseball_jersey_red.png?1442035822",
+          "large": "/spree/products/1/large/ror_baseball_jersey_red.png?1442035822"
+        }
+      },
+      "relationships": {
+        "viewable": {
+          "data": {
+            "type": "spree_variants",
+            "id": "1"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+List all of the images stored in the database.
+
+## Show Image
+
+```shell
+curl "https://kabuni.com/api/v2/images/1"
+```
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "spree_images",
+    "attributes": {
+      "position": 1,
+      "alt": null,
+      "links": {
+        "original": "/spree/products/1/original/ror_baseball_jersey_red.png?1442035822",
+        "mini": "/spree/products/1/mini/ror_baseball_jersey_red.png?1442035822",
+        "small": "/spree/products/1/small/ror_baseball_jersey_red.png?1442035822",
+        "product": "/spree/products/1/product/ror_baseball_jersey_red.png?1442035822",
+        "large": "/spree/products/1/large/ror_baseball_jersey_red.png?1442035822"
+      }
+    },
+    "relationships": {
+      "viewable": {
+        "data": {
+          "type": "spree_variants",
+          "id": "1"
+        }
+      }
+    }
+  }
+}
+```
+
+Fetch an image and its links via the image's `id`.
+
+## Show Variant of an Image
+
+```shell
+curl "https://kabuni.com/api/v2/images/1/variant"
+```
+
+```json
+{
+  "data": {
+    "id": "17",
+    "type": "spree_variants",
+    "attributes": {
+      "sku": "ROR-00001",
+      "weight": "0.0",
+      "height": null,
+      "width": null,
+      "depth": null,
+      "is_master": false,
+      "position": 2,
+      "name": "Ruby on Rails Baseball Jersey",
+      "price": null,
+      "display_price": "$0.00 CAD"
+    },
+    "relationships": {
+      "prices": {
+        "data": [
+          {
+            "type": "spree_prices",
+            "id": "33"
+          }
+        ]
+      },
+      "option_values": {
+        "data": [
+          {
+            "type": "spree_option_values",
+            "id": "1"
+          }
+        ]
+      },
+      "images": {
+        "data": [
+          {
+            "type": "spree_images",
+            "id": "1"
+          }
+        ]
+      },
+      "product": {
+        "data": {
+          "type": "spree_products",
+          "id": "3"
+        }
+      }
+    }
+  }
+}
+```
+
+Fetch the variant that an image belongs to via the variant's `id`.
+
+## Show Product of an Image
+
+```shell
+curl "https://kabuni.com/api/v2/images/1/product"
+```
+
+```json
+{
+  "data": {
+    "id": "3",
+    "type": "spree_products",
+    "attributes": {
+      "name": "Ruby on Rails Baseball Jersey",
+      "description": "Dolorem molestias sint maxime id at rem qui exercitationem. Neque voluptas corrupti magni suscipit iusto voluptatum. Ea quibusdam dolorem inventore praesentium sed dicta eveniet et. Rerum inventore laudantium quisquam earum consequatur dignissimos.",
+      "slug": "ruby-on-rails-baseball-jersey",
+      "meta_description": null,
+      "meta_keywords": null,
+      "store_name": "Whole New Home"
+    },
+    "relationships": {
+      "master": {
+        "data": {
+          "type": "spree_variants",
+          "id": "3"
+        }
+      },
+      "variants": {
+        "data": [
+          {
+            "type": "spree_variants",
+            "id": "1"
+          }
+        ]
+      },
+      "taxons": {
+        "data": [
+          {
+            "type": "spree_taxons",
+            "id": "53"
+          }
+        ]
+      },
+      "option_types": {
+        "data": [
+          {
+            "type": "spree_option_types",
+            "id": "1"
+          }
+        ]
+      },
+      "images": {
+        "data": [
+          {
+            "type": "spree_images",
+            "id": "24"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Find the product that image belongs to via the image's `id`.

data/docs/source/includes/_line_items.md

@@ -0,0 +1,137 @@
+# Line Items
+
+## Create Line Item
+
+```shell
+curl "https://kabuni.com/api/v2/line_items"
+  -X POST
+  -d token=abc123
+  -d line_item[order_id]=1
+  -d line_item[variant_id]=1
+  -d line_item[quantity]=1
+```
+
+```json
+{
+  "data" : {
+    "attributes" : {
+      "additional_tax_total" : 0,
+      "adjustment_total" : 0.0,
+      "amount" : "10.0",
+      "cost_price" : "17.0",
+      "currency" : "CAD",
+      "display_amount" : "$10.00 CAD",
+      "display_price" : "$10.00 CAD",
+      "display_total" : "$10.00 CAD",
+      "order_id" : 1,
+      "price" : "10.0",
+      "quantity" : 1,
+      "total" : "10.0",
+      "variant_id" : 1
+    },
+    "relationships" : {
+      "order" : {
+        "data" : {
+          "type" : "spree_orders"
+        }
+      },
+      "variant" : {
+        "data" : {
+          "type" : "spree_variants"
+        }
+      }
+    },
+    "type" : "spree_line_items"
+  }
+}
+```
+
+This endpoint allows you add a variant to a users order by creating a line item.
+
+### When Out of Range
+
+> Quantity is out of range.
+
+```shell
+curl "https://kabuni.com/api/v2/line_items"
+  -X POST
+  -d token=abc123
+  -d line_item[order_id]=1
+  -d line_item[variant_id]=1
+  -d line_item[quantity]=100000000000
+```
+
+```json
+{
+  "errors" : [
+    {
+      "detail" : "Quantity is too High",
+      "meta" : {},
+      "title" : "The quantity that you have submitted is astronomically high, please tone it down a bit."
+    }
+  ]
+}
+```
+
+When requesting an insanely large amount of variants to be added to your order, this will result in an error.
+
+### When a Variant or an Order Could Not be Found
+
+> Order could not be found.
+
+```shell
+curl "https://kabuni.com/api/v2/line_items"
+  -X POST
+  -d token=abc123
+  -d line_item[order_id]=0
+  -d line_item[variant_id]=1
+  -d line_item[quantity]=1
+```
+
+```json
+{
+  "errors" : [
+    {
+      "detail" : "Record Not Found",
+      "meta" : {},
+      "title" : "One of the records that you were looking for could not be found. Please check to see if the record exists or if you're permitted to read it"
+    }
+  ]
+}
+```
+
+Sometimes, you'll submit a bad variant id or order id.
+When this happens, you'll receive an error because of it.
+
+### When the Product is Out of Stock
+
+> Product is out of stock.
+
+```shell
+curl "https://kabuni.com/api/v2/line_items"
+  -X POST
+  -d token=abc123
+  -d line_item[order_id]=1
+  -d line_item[variant_id]=1
+  -d line_item[quantity]=1
+```
+
+```json
+{
+  "errors" : [
+    {
+      "detail" : "Product is out of Stock",
+      "meta" : {},
+      "title" : "This product is out of stock for the selected quantity."
+    }
+  ]
+}
+```
+
+Sometimes, there's just not going to be any left in stock.
+This can happen for both two reasons:
+
+1. The variant is tracking inventory and its stock items `count_on_hand`s have all reached 0.
+2. The variant is not backorderable.
+
+If both of these conditions are met, then you will reveice an out of stock error.