solidus_api 2.9.5 → 2.10.2

data/openapi/authentication.md

@@ -0,0 +1,25 @@
+# Authentication
+
+The Solidus API provides two means of authentication: one is through your Solidus user's API key, while the other is through an order's guest token.
+
+### API key
+
+You can use your API key to access all resources in the API. The API key must be passed in the `Authorization` header in the following form:
+
+```
+Authorization: Bearer API_KEY
+```
+
+By default, API keys are only generated for admins, but you can easily customize Solidus to generate them for all users, which is useful for instance if you want users to be able to sign in and manage their profile via the API.
+
+### Order token
+
+For allowing guests to manage their cart and place their order, you can use the order's guest token. This token is contained in the `guest_token` property of the order, and it allows you to perform certain checkout-related operations on the order such as managing line items, completing the checkout flow etc.
+
+The order token must be passed in the `X-Spree-Order-Token` header in the following form:
+
+```
+X-Spree-Order-Token: ORDER_TOKEN
+```
+
+If you are already providing an API key, you don't need to also provide the order token (although you may do so).

data/openapi/checkout-flow.md

@@ -0,0 +1,50 @@
+# Checkout flow
+
+Given the amount of endpoints at your disposal, it can be difficult to understand how to string the right API calls together to perform a full checkout flow. This document explains how to perform a full checkout flow.
+
+## 1. Create an order
+
+The first step is to create an order via `POST /orders`. You should save the number of the order that is created as well as the guest token, in case you are not authenticating with an API key.
+
+## 2. Fill the cart
+
+Once you have an order, you can begin filling your cart. Here are some endpoints you can use for that:
+
+- `POST /checkouts/:order_number/line_items`
+- `PATCH /checkouts/:order_number/line_items/:id`
+- `DELETE /checkouts/:order_number/line_items/:id`
+- `PUT /orders/:order_number/empty`
+
+## 3. (Optional) Apply a coupon code
+
+You can also apply a coupon code on the order via `POST /orders/:order_number/coupon_codes`.
+
+## 4. Start the checkout flow
+
+When you are ready to start the checkout flow, you can call `PUT /checkouts/:order_number/next` to transition the order from the `cart` to the `address` state.
+
+## 5. Enter billing and shipping addresses
+
+To enter the billing and shipping addresses, use the `PATCH /checkouts/:order_number` endpoint.
+
+Once again, call `PUT /checkouts/:order_number/next` to transition the order from the `address` to the `shipping` state.
+
+## 6. Select a shipping method
+
+You can retrieve the available shipping methods, along with their rates, via `GET /shipments/:shipment_number/estimated_rates`. This allows you to let your user choose the shipping method they prefer.
+
+When you want to select a shipping method, call `PUT /shipments/:shipment_number/select_shipping_method`.
+
+Finally, call `PUT /checkouts/:order_number/next` to transition the order from the `shipping` to the `payment` state.
+
+## 7. Enter payment details
+
+To create a payment, call `POST /orders/:order_number/payments`.
+
+Now call `PUT /checkouts/:order_number/next` to transition the order from the `payment` to the `confirm` state.
+
+## 8. Complete the order
+
+At this point, you should show the user a summary of their cart and ask them to confirm they want to place the order.
+
+When they confirm, call `PUT /checkouts/:order_number/complete` to complete the checkout flow and place the order!

data/openapi/errors.md

@@ -0,0 +1,3 @@
+# Errors
+
+Error responses for each endpoint are documented. When interacting with an endpoint, make sure to handle all possible errors appropriately.

data/openapi/lint.yml

@@ -0,0 +1 @@
+rules: {}

data/openapi/main.hub.yml

@@ -0,0 +1,65 @@
+title: Solidus API
+logo: 'https://next.stoplight.io/images/mark-light-bg.png'
+header:
+  nav:
+    left: []
+    right: []
+pages:
+  /:
+    title: Welcome
+    data:
+      blocks:
+        - type: text
+          data: >-
+            # Solidus API
+
+
+            Welcome! This is the documentation for the
+            [Solidus](https://solidus.io) REST API.
+
+
+            This documentation refers to a stock installation of Solidus.
+            However, every store may customize their API in any number of ways,
+            so make sure to ensure the store you are working with conforms to
+            this documentation or refer to the store's own documentation for
+            interacting with the API.
+
+
+            Endpoints are grouped by the logical resource they interact with.
+            Note that some of the endpoints are duplicated, since the same
+            resource may be accessed at the root level or as the child of
+            another resource (e.g. you may access all variants or the variants
+            that belong to a specific product).
+        - type: text
+          data: ''
+      children:
+        - title: Authentication
+          route:
+            path: /authentication
+          data:
+            $ref: ./authentication.md
+        - title: Pagination
+          route:
+            path: /pagination
+          data:
+            $ref: ./pagination.md
+        - title: Errors
+          route:
+            path: /errors
+          data:
+            $ref: ./errors.md
+        - title: Checkout Flow
+          route:
+            path: /checkout-flow
+          data:
+            $ref: ./checkout-flow.md
+          config:
+            sidebar:
+              token: ''
+        - title: API Reference
+          config:
+            includeDownloadLink: true
+          route:
+            path: /api-reference
+          data:
+            $ref: ./api.oas2.yml

data/openapi/pagination.md

@@ -0,0 +1,7 @@
+# Pagination
+
+Most endpoints that return a collection are paginated. A paginated response contains metadata about the current page at the root level and the resources in the current page in a child key named after the resource (e.g. `orders`).
+
+You can pass the `page` and `per_page` parameters to set the current page and the desired number of items per page. Note that the default and the maximum number of items per page is decided at the application level.
+
+All pagination metadata is documented in the individual API endpoints, so take a look there if you're unsure what data you can expect.

data/solidus_api.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version = Spree.solidus_version
 
-  gem.required_ruby_version = '>= 2.2.2'
+  gem.required_ruby_version = '>= 2.4.0'
   gem.required_rubygems_version = '>= 1.8.23'
 
   gem.add_dependency 'jbuilder', '~> 2.8'

data/spec/controllers/spree/api/resource_controller_spec.rb

@@ -25,10 +25,10 @@ module Spree
     end
 
     with_model 'Widget', scope: :all do
-      table do |t|
-        t.string :name
-        t.integer :position
-        t.timestamps null: false
+      table do |widget|
+        widget.string :name
+        widget.integer :position
+        widget.timestamps null: false
       end
 
       model do

data/spec/lib/spree_api_responders_spec.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe "Spree Api Responders" do
+  it "RablTemplate is deprecated Use JbuilderTemplate" do
+    warning_message = /DEPRECATION WARNING: RablTemplate is deprecated! Use JbuilderTemplate instead/
+    expect{ Spree::Api::Responders::RablTemplate.methods }.to output(warning_message).to_stderr
+  end
+end

data/spec/requests/api/address_books_spec.rb

@@ -80,7 +80,7 @@ module Spree
             user_address = UserAddress.last
 
             expect(response.status).to eq(200)
-            update_target_ids = JSON.parse(response.body).select { |a| a['update_target'] }.map { |a| a['id'] }
+            update_target_ids = JSON.parse(response.body).select { |target| target['update_target'] }.map { |location| location['id'] }
             expect(update_target_ids).to eq([user_address.address_id])
           end
         end
@@ -97,7 +97,7 @@ module Spree
             }.to_not change { UserAddress.count }
 
             expect(response.status).to eq(200)
-            update_target_ids = JSON.parse(response.body).select { |a| a['update_target'] }.map { |a| a['id'] }
+            update_target_ids = JSON.parse(response.body).select { |target| target['update_target'] }.map { |location| location['id'] }
             expect(update_target_ids).to eq([address.id])
           end
         end

data/spec/requests/{rabl_cache_spec.rb → jbuilder_cache_spec.rb}

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe "Rabl Cache", type: :request, caching: true do
+describe "Jbuilder Cache", type: :request, caching: true do
   let!(:user)  { create(:admin_user) }
 
   before do
@@ -11,7 +11,7 @@ describe "Rabl Cache", type: :request, caching: true do
     expect(Spree::Product.count).to eq(1)
   end
 
-  it "doesn't create a cache key collision for models with different rabl templates" do
+  it "doesn't create a cache key collision for models with different jbuilder templates" do
     get "/api/variants", params: { token: user.spree_api_key }
     expect(response.status).to eq(200)
 

data/spec/requests/spree/api/checkouts_controller_spec.rb

@@ -132,9 +132,9 @@ module Spree
         put spree.api_checkout_path(order.to_param), params: { order_token: order.guest_token, order: { shipments_attributes: { "0" => { selected_shipping_rate_id: shipping_rate.id, id: shipment.id } } } }
         expect(response.status).to eq(200)
         # Find the correct shipment...
-        json_shipment = json_response['shipments'].detect { |s| s["id"] == shipment.id }
+        json_shipment = json_response['shipments'].detect { |value| value["id"] == shipment.id }
         # Find the correct shipping rate for that shipment...
-        json_shipping_rate = json_shipment['shipping_rates'].detect { |sr| sr["id"] == shipping_rate.id }
+        json_shipping_rate = json_shipment['shipping_rates'].detect { |value| value["id"] == shipping_rate.id }
         # ... And finally ensure that it's selected
         expect(json_shipping_rate['selected']).to be true
         # Order should automatically transfer to payment because all criteria are met
@@ -172,6 +172,7 @@ module Spree
       end
 
       describe 'setting the payment amount' do
+        let(:order) { create(:order_with_line_items, state: :payment) }
         let(:params) do
           {
             order_token: order.guest_token,
@@ -322,17 +323,44 @@ module Spree
         end
       end
 
+      it "cannot update attributes of another step" do
+        order.update_column(:state, "payment")
+
+        params = {
+          order_token: order.guest_token,
+          order: {
+            payments_attributes: [
+              {
+                payment_method_id: @payment_method.id.to_s,
+                source_attributes: attributes_for(:credit_card)
+              }
+            ],
+            ship_address_attributes: {
+              zipcode: 'MALICIOUS ZIPCODE'
+            }
+          }
+        }
+        expect do
+          put spree.api_checkout_path(order), params: params
+        end.not_to change { order.reload.ship_address.zipcode }
+        expect(response.status).to eq(200)
+      end
+
       it "returns the order if the order is already complete" do
         order.update_columns(completed_at: Time.current, state: 'complete')
         put spree.api_checkout_path(order.to_param), params: { order_token: order.guest_token }
         assert_unauthorized!
       end
 
-      # Regression test for https://github.com/spree/spree/issues/3784
-      it "can update the special instructions for an order" do
-        instructions = "Don't drop it. (Please)"
-        put spree.api_checkout_path(order.to_param), params: { order_token: order.guest_token, order: { special_instructions: instructions } }
-        expect(json_response['special_instructions']).to eql(instructions)
+      context "in delivery state" do
+        let(:order) { create(:order_with_line_items, state: :delivery) }
+
+        # Regression test for https://github.com/spree/spree/issues/3784
+        it "can update the special instructions for an order" do
+          instructions = "Don't drop it. (Please)"
+          put spree.api_checkout_path(order.to_param), params: { order_token: order.guest_token, order: { special_instructions: instructions } }
+          expect(json_response['special_instructions']).to eql(instructions)
+        end
       end
 
       context "as an admin" do

data/spec/requests/spree/api/classifications_controller_spec.rb

@@ -39,7 +39,7 @@ module Spree
       end
 
       it "should touch the taxon" do
-        taxon.update_attributes(updated_at: Time.current - 10.seconds)
+        taxon.update(updated_at: Time.current - 10.seconds)
         taxon_last_updated_at = taxon.updated_at
         put spree.api_classifications_path, params: { taxon_id: taxon.id, product_id: last_product.id, position: 0 }
         taxon.reload

data/spec/requests/spree/api/option_types_controller_spec.rb

@@ -34,9 +34,9 @@ module Spree
     end
 
     it "can retrieve a list of specific option types" do
-      option_type_1 = create(:option_type)
+      option_type_one = create(:option_type)
       create(:option_type)
-      get spree.api_option_types_path, params: { ids: "#{option_type.id},#{option_type_1.id}" }
+      get spree.api_option_types_path, params: { ids: "#{option_type.id},#{option_type_one.id}" }
       expect(json_response.count).to eq(2)
 
       check_option_values(json_response.first["option_values"])

data/spec/requests/spree/api/option_values_controller_spec.rb

@@ -48,9 +48,9 @@ module Spree
       end
 
       it "can retrieve a list of option types" do
-        option_value_1 = create(:option_value, option_type: option_type)
+        option_value_one = create(:option_value, option_type: option_type)
         create(:option_value, option_type: option_type)
-        get spree.api_option_values_path, params: { ids: [option_value.id, option_value_1.id] }
+        get spree.api_option_values_path, params: { ids: [option_value.id, option_value_one.id] }
         expect(json_response.count).to eq(2)
       end
 

data/spec/requests/spree/api/orders_controller_spec.rb

@@ -156,6 +156,7 @@ module Spree
         end
 
         context 'creating payment' do
+          let!(:order) { create(:order_with_line_items) }
           let(:order_params) { super().merge(payments_attributes: [{ payment_method_id: payment_method.id }]) }
 
           context "with allowed payment method" do
@@ -166,6 +167,28 @@ module Spree
                 subject
               }.to change { Spree::Payment.count }.by(1)
             end
+
+            context 'trying to change the address' do
+              let(:order_params) do
+                super().merge(
+                  ship_address_attributes: {
+                    zipcode: '90100'
+                  }
+                )
+              end
+
+              it 'changes the address' do
+                expect {
+                  subject
+                }.to change { order.reload.ship_address.zipcode }
+              end
+
+              it 'invalidates the shipments' do
+                expect {
+                  subject
+                }.to change { order.reload.shipments }.to([])
+              end
+            end
           end
 
           context "with disallowed payment method" do
@@ -246,12 +269,12 @@ module Spree
       it "returns orders in reverse chronological order by completed_at" do
         order.update_columns completed_at: Time.current, created_at: 3.days.ago
 
-        order2 = Order.create user: order.user, completed_at: Time.current - 1.day, created_at: 2.day.ago, store: store
-        expect(order2.created_at).to be > order.created_at
-        order3 = Order.create user: order.user, completed_at: nil, created_at: 1.day.ago, store: store
-        expect(order3.created_at).to be > order2.created_at
-        order4 = Order.create user: order.user, completed_at: nil, created_at: 0.days.ago, store: store
-        expect(order4.created_at).to be > order3.created_at
+        order_two = Order.create user: order.user, completed_at: Time.current - 1.day, created_at: 2.days.ago, store: store
+        expect(order_two.created_at).to be > order.created_at
+        order_three = Order.create user: order.user, completed_at: nil, created_at: 1.day.ago, store: store
+        expect(order_three.created_at).to be > order_two.created_at
+        order_four = Order.create user: order.user, completed_at: nil, created_at: 0.days.ago, store: store
+        expect(order_four.created_at).to be > order_three.created_at
 
         get spree.api_my_orders_path, headers: { 'SERVER_NAME' => store.url }
         expect(response.status).to eq(200)
@@ -259,8 +282,8 @@ module Spree
         orders = json_response["orders"]
         expect(orders.length).to eq(4)
         expect(orders[0]["number"]).to eq(order.number)
-        expect(orders[1]["number"]).to eq(order2.number)
-        expect([orders[2]["number"], orders[3]["number"]]).to match_array([order3.number, order4.number])
+        expect(orders[1]["number"]).to eq(order_two.number)
+        expect([orders[2]["number"], orders[3]["number"]]).to match_array([order_three.number, order_four.number])
       end
     end
 
@@ -306,7 +329,7 @@ module Spree
 
       context 'when an item does not track inventory' do
         before do
-          order.line_items.first.variant.update_attributes!(track_inventory: false)
+          order.line_items.first.variant.update!(track_inventory: false)
         end
 
         it 'contains stock information on variant' do
@@ -502,18 +525,18 @@ module Spree
       end
 
       it "adds an extra line item" do
-        variant2 = create(:variant)
+        variant_two = create(:variant)
         put spree.api_order_path(order), params: { order: {
           line_items: {
             "0" => { id: line_item.id, quantity: 10 },
-            "1" => { variant_id: variant2.id, quantity: 1 }
+            "1" => { variant_id: variant_two.id, quantity: 1 }
           }
         } }
 
         expect(response.status).to eq(200)
         expect(json_response['line_items'].count).to eq(2)
         expect(json_response['line_items'][0]['quantity']).to eq(10)
-        expect(json_response['line_items'][1]['variant_id']).to eq(variant2.id)
+        expect(json_response['line_items'][1]['variant_id']).to eq(variant_two.id)
         expect(json_response['line_items'][1]['quantity']).to eq(1)
       end
 
@@ -547,7 +570,7 @@ module Spree
       end
 
       it "can add shipping address" do
-        order.update_attributes!(ship_address_id: nil)
+        order.update!(ship_address_id: nil)
 
         expect {
           put spree.api_order_path(order), params: { order: { ship_address_attributes: shipping_address } }
@@ -555,7 +578,7 @@ module Spree
       end
 
       it "receives error message if trying to add shipping address with errors" do
-        order.update_attributes!(ship_address_id: nil)
+        order.update!(ship_address_id: nil)
 
         shipping_address[:firstname] = ""
 
@@ -727,7 +750,7 @@ module Spree
 
           orders = json_response[:orders]
           expect(orders.count).to be >= 3
-          expect(orders.map { |o| o[:id] }).to match_array Order.pluck(:id)
+          expect(orders.map { |order| order[:id] }).to match_array Order.pluck(:id)
         end
 
         after { ActionController::Base.perform_caching = false }