Customizing the Spree API

Customizing JSON Responses

Adding Custom Attributes

module MyApp
  class ProductSerializer < Spree::Api::V3::ProductSerializer
    attribute :my_custom_attribute
  end
end

Spree::Api::Dependencies.product_serializer = 'MyApp::ProductSerializer'

Adding an Association

module Spree
  module Api
    module V3
      class BrandSerializer < BaseSerializer
        typelize name: :string, slug: [:string, nullable: true]

        attributes :name, :slug
      end
    end
  end
end

module MyApp
  class ProductSerializer < Spree::Api::V3::ProductSerializer
    typelize brand_id: [:string, nullable: true]

    attribute :brand_id do |product|
      product.brand&.prefixed_id
    end

    one :brand,
        resource: Spree::Api::V3::BrandSerializer,
        if: proc { expand?('brand') }
  end
end

Spree::Api::Dependencies.product_serializer = 'MyApp::ProductSerializer'

GET /api/v3/store/products/prod_86Rf07xd4z?expand=brand

Adding a Field from an Extension

Rails.application.config.after_initialize do
  Spree.api.extension_fields.attribute(:admin_product_serializer, method: :warranty_text)

  Spree.api.extension_fields.association(
    :admin_product_serializer,
    one: :warranty,
    serializer: 'MyExtension::WarrantySerializer',
    expand: true
  )

  Spree.api.extension_fields.association(
    :admin_product_serializer,
    many: :warranty_claims,
    serializer: 'MyExtension::ClaimSerializer',
    expand: true
  )
end

• The name is the response key and the record’s method that gives the value: method: for an attribute, one: or many: for an association. one: :warranty writes product.warranty with the given serializer; many: :warranty_claims writes each of product.warranty_claims. An extension adds such methods to core models with model extensions.
• A simple computed value needs no method: name the field and pass value:, as in attribute(:admin_product_serializer, :warranty_months, value: ->(product) { ... }). An association takes value: the same way, beside its one: or many:.
• Registered by dependency key, such as admin_product_serializer. If the application replaces that serializer with one that inherits from a core serializer, as shown above, the field still renders on the replacement.
• expand: true shows the field only when the request asks for it with ?expand=warranty. Without it, the field is always shown. An association’s nested expands reach its serializer, so ?expand=warranty.claims passes claims on, the same way ?expand=variants.media works. Lists apply the same expands to every item.
• Associations read on lists are batched when they are Active Record associations, as core ones are. A value computed by value: is read for each record.
• Names are unique per serializer. Registering a name that the serializer or another extension already uses raises an error at boot.
• Not in the generated SDK types. The extension that adds a field declares its TypeScript type.

Serializer Dependency Keys

Adding New Endpoints

Controller

module Spree
  module Api
    module V3
      module Store
        class BrandsController < ResourceController
          protected

          def model_class
            Spree::Brand
          end

          def serializer_class
            Spree::Api::V3::BrandSerializer
          end

          def scope
            Spree::Brand.all
          end
        end
      end
    end
  end
end

Routes

Spree::Core::Engine.add_routes do
  namespace :api, defaults: { format: 'json' } do
    namespace :v3 do
      namespace :store do
        resources :brands, only: [:index, :show]
      end
    end
  end
end

Request Parameters

request_params :brand do |body|
  body.attribute :name, :string, required: true, on: :create
  body.attribute :slug, :string
  body.attribute :description, :string, description: 'Shown on the brand page.'
  body.attribute :region_ids, :array, of: :id
  body.attribute :metadata, :hash
end

module Spree
  module Api
    module V3
      class BrandLogoRequestSchema < Spree::Api::V3::RequestSchema
        publishes 'BrandLogoParams'

        attribute :signed_id, :string, required: true
        attribute :alt, :string
      end
    end
  end
end

Adding an Attribute to a Core Resource

Rails.application.config.to_prepare do
  Spree::Product.additional_permitted_attributes += [:brand_id]
end

Rails.application.config.to_prepare do
  Spree::Media.additional_permitted_attributes += [:photo_credit]
end

Writable by sellers

Spree::Product.additional_seller_permitted_attributes += [:brand_id]

From an endpoint to agent tools and an SDK client

1. Scaffold it. spree generate api_resource Brand name:string writes the model, the controllers with their request_params, the serializers, the routes, the permission and the specs, including an Admin integration spec that documents the endpoints.
2. Document it. The integration specs are rswag specs using Spree’s helpers: admin_operation for authentication and the permission, request_body_for for the body request_params declares, filter_parameters_for for list filters. spree task openapi:generate (bundle exec rake spree:openapi:generate in an extension) writes them into openapi/admin.yaml, and openapi/store.yaml for Store API endpoints. See documenting your endpoints.
3. Agent tools follow. Every documented admin action other than create, read, update and delete is an agent tool in the Admin MCP and the dashboard assistant, with nothing to register. spec/agent_tools_spec.rb fails when an action is added undocumented.
4. Generate the client. In an npm package for the extension, spree sdk generate writes one SDK extension per resource, with a method per documented operation, and the request, filter and response types. An app adds them to its client with extendAdminClient(createAdminClient(…)) or extendStoreClient(createClient(…)). See shipping a client for an extension.