solidus_api 2.9.6 → 2.11.0

data/app/controllers/spree/api/variants_controller.rb

@@ -43,7 +43,7 @@ module Spree
 
       def update
         @variant = scope.accessible_by(current_ability, :update).find(params[:id])
-        if @variant.update_attributes(variant_params)
+        if @variant.update(variant_params)
           respond_with(@variant, status: 200, default_template: :show)
         else
           invalid_resource!(@product)
@@ -53,7 +53,7 @@ module Spree
       private
 
       def product
-        @product ||= Spree::Product.accessible_by(current_ability, :read).friendly.find(params[:product_id]) if params[:product_id]
+        @product ||= Spree::Product.accessible_by(current_ability, :show).friendly.find(params[:product_id]) if params[:product_id]
       end
 
       def scope
@@ -64,12 +64,12 @@ module Spree
         end
 
         if current_ability.can?(:manage, Variant) && params[:show_deleted]
-          variants = variants.with_deleted
+          variants = variants.with_discarded
         end
 
         in_stock_only = ActiveRecord::Type::Boolean.new.cast(params[:in_stock_only])
         suppliable_only = ActiveRecord::Type::Boolean.new.cast(params[:suppliable_only])
-        variants = variants.accessible_by(current_ability, :read)
+        variants = variants.accessible_by(current_ability)
         if in_stock_only || cannot?(:view_out_of_stock, Spree::Variant)
           variants = variants.in_stock
         elsif suppliable_only

data/app/controllers/spree/api/zones_controller.rb

@@ -21,7 +21,7 @@ module Spree
 
       def index
         @zones = Spree::Zone.
-          accessible_by(current_ability, :read).
+          accessible_by(current_ability).
           order('name ASC').
           ransack(params[:q]).
           result
@@ -37,7 +37,7 @@ module Spree
 
       def update
         authorize! :update, zone
-        if zone.update_attributes(zone_params)
+        if zone.update(zone_params)
           respond_with(zone, status: 200, default_template: :show)
         else
           invalid_resource!(zone)
@@ -55,7 +55,7 @@ module Spree
       end
 
       def zone
-        @zone ||= Spree::Zone.accessible_by(current_ability, :read).find(params[:id])
+        @zone ||= Spree::Zone.accessible_by(current_ability, :show).find(params[:id])
       end
     end
   end

data/app/helpers/spree/api/api_helpers.rb

@@ -22,6 +22,7 @@ module Spree
         :state_attributes,
         :adjustment_attributes,
         :inventory_unit_attributes,
+        :customer_return_attributes,
         :return_authorization_attributes,
         :creditcard_attributes,
         :payment_source_attributes,
@@ -40,7 +41,7 @@ module Spree
 
       def required_fields_for(model)
         required_fields = model._validators.select do |_field, validations|
-          validations.any? { |v| v.is_a?(ActiveModel::Validations::PresenceValidator) }
+          validations.any? { |validation| validation.is_a?(ActiveModel::Validations::PresenceValidator) }
         end.map(&:first) # get fields that are invalid
         # Permalinks presence is validated, but are really automatically generated
         # Therefore we shouldn't tell API clients that they MUST send one through
@@ -117,16 +118,27 @@ module Spree
         :id, :state, :variant_id, :shipment_id
       ]
 
+      @@customer_return_attributes = [
+        :id, :number, :stock_location_id, :created_at, :updated_at
+      ]
+
       @@return_authorization_attributes = [
         :id, :number, :state, :order_id, :memo, :created_at, :updated_at
       ]
 
-      @@address_attributes = [
-        :id, :firstname, :lastname, :full_name, :address1, :address2, :city,
-        :zipcode, :phone, :company, :alternative_phone, :country_id, :country_iso,
-        :state_id, :state_name, :state_text
+      @@address_base_attributes = [
+        :id, :name, :address1, :address2, :city, :zipcode, :phone, :company,
+        :alternative_phone, :country_id, :country_iso, :state_id, :state_name,
+        :state_text
       ]
 
+      @@address_attributes = if Spree::Config.use_combined_first_and_last_name_in_address
+                               @@address_base_attributes
+                             else
+                               @@address_base_attributes +
+                                 Spree::Address::LEGACY_NAME_ATTRS.map(&:to_sym)
+                             end
+
       @@country_attributes = [:id, :iso_name, :iso, :iso3, :name, :numcode]
 
       @@state_attributes = [:id, :name, :abbr, :country_id]
@@ -168,7 +180,8 @@ module Spree
 
       @@store_attributes = [
         :id, :name, :url, :meta_description, :meta_keywords, :seo_title,
-        :mail_from_address, :default_currency, :code, :default, :available_locales
+        :mail_from_address, :default_currency, :code, :default, :available_locales,
+        :bcc_email
       ]
 
       @@store_credit_history_attributes = [
@@ -177,7 +190,7 @@ module Spree
       ]
 
       def variant_attributes
-        if @current_user_roles && @current_user_roles.include?("admin")
+        if @current_user_roles&.include?("admin")
           @@variant_attributes + [:cost_price]
         else
           @@variant_attributes

data/app/views/spree/api/customer_returns/index.json.jbuilder

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+json.customer_returns(@customer_returns) do |customer_return|
+  json.(customer_return, *customer_return_attributes)
+end
+json.partial! 'spree/api/shared/pagination', pagination: @customer_returns

data/app/views/spree/api/customer_returns/new.json.jbuilder

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+json.attributes([*customer_return_attributes])
+json.required_attributes(required_fields_for(Spree::CustomerReturn))

data/app/views/spree/api/customer_returns/show.json.jbuilder

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+json.(@customer_return, *customer_return_attributes)

data/app/views/spree/api/errors/could_not_transition.json.jbuilder

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+json.error(I18n.t(:could_not_transition, scope: "spree.api", resource: resource.class.name.demodulize.underscore))
+json.errors(resource.errors.to_hash)

data/app/views/spree/api/images/_image.json.jbuilder

@@ -2,6 +2,6 @@
 
 json.(image, *image_attributes)
 json.(image, :viewable_type, :viewable_id)
-Spree::Image.attachment_definitions[:attachment][:styles].each do |k, _v|
-  json.set! "#{k}_url", image.attachment.url(k)
+Spree::Image.attachment_definitions[:attachment][:styles].each do |key, _value|
+  json.set! "#{key}_url", image.attachment.url(key)
 end

data/app/views/spree/api/orders/_order.json.jbuilder

@@ -3,7 +3,7 @@
 json.cache! [I18n.locale, order] do
   json.(order, *order_attributes)
   json.display_item_total(order.display_item_total.to_s)
-  json.total_quantity(order.line_items.sum(:quantity))
+  json.total_quantity(order.line_items.to_a.sum(&:quantity))
   json.display_total(order.display_total.to_s)
   json.display_ship_total(order.display_ship_total)
   json.display_tax_total(order.display_tax_total)

data/app/views/spree/api/orders/could_not_transition.json.jbuilder

@@ -1,4 +1,9 @@
 # frozen_string_literal: true
 
+Spree::Deprecation.warn(
+  'spree/api/orders/could_not_transition is deprecated.' \
+  ' Please use spree/api/errors/could_not_transition'
+)
+
 json.error(I18n.t(:could_not_transition, scope: "spree.api.order"))
 json.errors(@order.errors.to_hash)

data/app/views/spree/api/shared/_pagination.json.jbuilder

@@ -4,4 +4,4 @@ json.count        pagination.count
 json.total_count  pagination.total_count
 json.current_page pagination.current_page
 json.pages        pagination.total_pages
-json.per_page     pagination.current_per_page
+json.per_page     pagination.limit_value

data/config/locales/en.yml

@@ -8,6 +8,8 @@ en:
       invalid_resource: Invalid resource. Please fix errors and try again.
       invalid_taxonomy_id: Invalid taxonomy id.
       must_specify_api_key: You must specify an API key.
+      could_not_transition: The %{resource} could not be transitioned. Please fix the
+        errors and try again.
       order:
         could_not_transition: The order could not be transitioned. Please fix the
           errors and try again.

data/config/routes.rb

@@ -3,9 +3,11 @@
 Spree::Core::Engine.routes.draw do
   namespace :admin do
     resources :users do
+      resource :api_key, controller: 'users/api_key', only: [:create, :destroy]
+
       member do
-        put :generate_api_key
-        put :clear_api_key
+        put :generate_api_key # Deprecated
+        put :clear_api_key # Deprecated
       end
     end
   end
@@ -38,6 +40,8 @@ Spree::Core::Engine.routes.draw do
           put :cancel
         end
       end
+
+      resources :customer_returns, except: :destroy
     end
 
     resources :checkouts, only: [:update], concerns: :order_routes do
@@ -57,7 +61,6 @@ Spree::Core::Engine.routes.draw do
     end
     resources :option_values
 
-    resources :option_values, only: :index
     get '/orders/mine', to: 'orders#mine', as: 'my_orders'
     get "/orders/current", to: "orders#current", as: "current_order"
 

data/lib/spree/api.rb

@@ -2,11 +2,4 @@
 
 require 'spree/core'
 
-require 'responders'
-
-module Spree
-  module Api
-  end
-end
-
 require 'spree/api/engine'

data/lib/spree/api/config.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'spree/api_configuration'
+
+module Spree
+  module Api
+    Config = Spree::ApiConfiguration.new
+  end
+end

data/lib/spree/api/engine.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rails/engine'
+require 'spree/api/config'
 
 module Spree
   module Api
@@ -8,9 +8,9 @@ module Spree
       isolate_namespace Spree
       engine_name 'spree_api'
 
-      initializer "spree.api.environment", before: :load_config_initializers do |_app|
-        Spree::Api::Config = Spree::ApiConfiguration.new
-      end
+      # Leave initializer empty for backwards-compatability. Other apps
+      # might still rely on this event.
+      initializer "spree.api.environment", before: :load_config_initializers do; end
     end
   end
 end

data/lib/spree/api/responders.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require 'spree/api/responders/rabl_template'
+require 'responders'
+require 'spree/api/responders/jbuilder_template'
 
 module Spree
   module Api
     module Responders
       class AppResponder < ActionController::Responder
-        include RablTemplate
+        include JbuilderTemplate
       end
     end
   end

data/lib/spree/api/responders/{rabl_template.rb → jbuilder_template.rb}

@@ -3,7 +3,7 @@
 module Spree
   module Api
     module Responders
-      module RablTemplate
+      module JbuilderTemplate
         def to_format
           if template
             render template, status: options[:status] || 200
@@ -16,6 +16,8 @@ module Spree
           options[:default_template]
         end
       end
+
+      RablTemplate = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('RablTemplate', 'JbuilderTemplate')
     end
   end
 end

data/lib/spree/api/testing_support/helpers.rb

@@ -38,7 +38,7 @@ module Spree
         end
 
         def upload_image(filename)
-          fixture_file_upload(image(filename).path, 'image/jpg')
+          Rack::Test::UploadedFile.new(File.open(image(filename).path), 'image/jpg')
         end
       end
     end

data/openapi/.stoplight.yml

@@ -0,0 +1,7 @@
+stoplight: '1.0'
+environments:
+  default:
+    host: 'http://todos.stoplight.io'
+    todosApiKey: 123
+  staging: {}
+  production: {}

data/openapi/authentication.md

@@ -0,0 +1,33 @@
+# 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
+```
+
+As an admin, you can find your API token in the admin section under Users > Your e-email > API Access (at `admin/users/<user_id>/edit`)
+
+Example:
+
+```
+curl --header "Authorization: Bearer 1a6a9936ad150a2ee345c65331da7a3ccc2de" http://www.my-solidus-site.com/api/stores
+```
+
+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,63 @@
+# 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.
+
+The `checkouts#update` endpoint always advance the order to the next state. If the above request is successful, the order should now be in the `delivery` state.
+
+## 6. Select a shipping method
+
+You can retrieve the available shipping methods, along with their rates, via `GET /orders/:order_number` or `GET /orders/current`. This allows you to let your user choose the shipping method they prefer.
+
+When you want to select a shipping method, call `PUT /checkouts/:order_number`:
+
+```
+  {
+    "order": {
+      "shipments_attributes": {
+        "0": {
+          "selected_shipping_rate_id": :shipping_rate_id,
+          "id": :shipment_id
+        }
+      }
+    }
+  }
+```
+
+If the above request is successful, the order should now be in 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: ./solidus-api.oas.yml