solidus_api 2.9.6 → 2.10.0.beta1

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/spec/requests/spree/api/checkouts_controller_spec.rb

@@ -172,7 +172,6 @@ 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,
@@ -323,44 +322,17 @@ 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
 
-      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
+      # 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
 
       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/orders_controller_spec.rb

@@ -156,7 +156,6 @@ 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
@@ -167,28 +166,6 @@ 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
@@ -329,7 +306,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
@@ -570,7 +547,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 } }
@@ -578,7 +555,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] = ""
 

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

@@ -137,7 +137,7 @@ module Spree
       context "for a given payment" do
         context "updating" do
           it "can update" do
-            payment.update_attributes(state: 'pending')
+            payment.update(state: 'pending')
             put spree.api_order_payment_path(order, payment), params: { payment: { amount: 2.01 } }
             expect(response.status).to eq(200)
             expect(payment.reload.amount).to eq(2.01)
@@ -145,14 +145,14 @@ module Spree
 
           context "update fails" do
             it "returns a 422 status when the amount is invalid" do
-              payment.update_attributes(state: 'pending')
+              payment.update(state: 'pending')
               put spree.api_order_payment_path(order, payment), params: { payment: { amount: 'invalid' } }
               expect(response.status).to eq(422)
               expect(json_response["error"]).to eq("Invalid resource. Please fix errors and try again.")
             end
 
             it "returns a 403 status when the payment is not pending" do
-              payment.update_attributes(state: 'completed')
+              payment.update(state: 'completed')
               put spree.api_order_payment_path(order, payment), params: { payment: { amount: 2.01 } }
               expect(response.status).to eq(403)
               expect(json_response["error"]).to eq("This payment cannot be updated because it is completed.")

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

@@ -25,7 +25,7 @@ module Spree
         end
 
         it "cannot list stock items for an inactive stock location" do
-          stock_location.update_attributes!(active: false)
+          stock_location.update!(active: false)
           get spree.api_stock_location_stock_items_path(stock_location)
           expect(response).to be_not_found
         end
@@ -39,7 +39,7 @@ module Spree
         end
 
         it "cannot see a stock item for an inactive stock location" do
-          stock_location.update_attributes!(active: false)
+          stock_location.update!(active: false)
           get spree.api_stock_location_stock_item_path(stock_location, stock_item)
           expect(response.status).to eq(404)
         end
@@ -155,7 +155,7 @@ module Spree
 
         context 'variant does not track inventory' do
           before do
-            variant.update_attributes(track_inventory: false)
+            variant.update(track_inventory: false)
           end
 
           it "doesn't set the stock item's count_on_hand" do
@@ -221,7 +221,7 @@ module Spree
 
           context 'not tracking inventory' do
             before do
-              stock_item.variant.update_attributes(track_inventory: false)
+              stock_item.variant.update(track_inventory: false)
             end
 
             it "doesn't set the stock item's count_on_hand" do
@@ -279,7 +279,7 @@ module Spree
 
           context 'not tracking inventory' do
             before do
-              stock_item.variant.update_attributes(track_inventory: false)
+              stock_item.variant.update(track_inventory: false)
             end
 
             it "doesn't update the stock item's count_on_hand" do

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

@@ -21,7 +21,7 @@ module Spree
         end
 
         it "cannot see inactive stock locations" do
-          stock_location.update_attributes!(active: false)
+          stock_location.update!(active: false)
           get spree.api_stock_locations_path
           expect(response).to be_successful
           stock_locations = json_response['stock_locations'].map { |sl| sl['name'] }
@@ -37,7 +37,7 @@ module Spree
         end
 
         it "cannot see inactive stock locations" do
-          stock_location.update_attributes!(active: false)
+          stock_location.update!(active: false)
           get spree.api_stock_location_path(stock_location)
           expect(response).to be_not_found
         end
@@ -84,7 +84,7 @@ module Spree
         end
 
         it "can see inactive stock locations" do
-          stock_location.update_attributes!(active: false)
+          stock_location.update!(active: false)
           get spree.api_stock_locations_path
           expect(response).to be_successful
           stock_locations = json_response['stock_locations'].map { |sl| sl['name'] }
@@ -122,7 +122,7 @@ module Spree
         end
 
         it "can see inactive stock locations" do
-          stock_location.update_attributes!(active: false)
+          stock_location.update!(active: false)
           get spree.api_stock_location_path(stock_location)
           expect(response).to be_successful
           expect(json_response['name']).to eq stock_location.name

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solidus_api
 version: !ruby/object:Gem::Version
-  version: 2.9.6
+  version: 2.10.0.beta1
 platform: ruby
 authors:
 - Solidus Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-16 00:00:00.000000000 Z
+date: 2019-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jbuilder
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.9.6
+        version: 2.10.0.beta1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.9.6
+        version: 2.10.0.beta1
 description: REST API for the Solidus e-commerce framework.
 email: contact@solidus.io
 executables: []
@@ -111,7 +111,6 @@ files:
 - app/controllers/spree/api/variants_controller.rb
 - app/controllers/spree/api/zones_controller.rb
 - app/helpers/spree/api/api_helpers.rb
-- app/models/spree/api_configuration.rb
 - app/views/.rubocop.yml
 - app/views/spree/api/address_books/show.json.jbuilder
 - app/views/spree/api/addresses/_address.json.jbuilder
@@ -230,13 +229,24 @@ files:
 - db/migrate/20131017162334_add_index_to_user_spree_api_key.rb
 - lib/solidus_api.rb
 - lib/spree/api.rb
+- lib/spree/api/config.rb
 - lib/spree/api/engine.rb
 - lib/spree/api/responders.rb
 - lib/spree/api/responders/rabl_template.rb
 - lib/spree/api/testing_support/caching.rb
 - lib/spree/api/testing_support/helpers.rb
 - lib/spree/api/testing_support/setup.rb
+- lib/spree/api_configuration.rb
 - lib/spree_api.rb
+- openapi/.stoplight.yml
+- openapi/api.oas2.yml
+- openapi/authentication.md
+- openapi/checkout-flow.md
+- openapi/errors.md
+- openapi/lint.yml
+- openapi/main.hub.yml
+- openapi/pagination.md
+- openapi/theme.css
 - script/rails
 - solidus_api.gemspec
 - spec/controllers/spree/api/base_controller_spec.rb
@@ -309,7 +319,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.8.23
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: REST API for the Solidus e-commerce framework.