Workarea API

workarea-api defines an HTTP API, using JSON as a data format, for programmatic access to your Workarea application. The Workarea API is used for many purposes, such as integration with external services, or providing an alternative user interface to your web store (like an on-premises kiosk or mobile application). As such, Workarea provides two separate APIs for different purposes:

The Admin API is only available to admin users with the necessary "API Access" permissions, and provides CRUD operations on all data models in the application. It's primarily used for integration with external service providers, such as an OMS or ERP.
The Storefront API has a slightly more complex authentication scheme, because it's used by end-users to browse and purchase items on the storefront. This API is suitable for building alternative user interfaces to Workarea

Getting Started

To begin using the Workarea API, add the following to your Gemfile:

  gem 'weblinc-api'

Next, mount the API engines into config/routes.rb.

You can either use a path prefix:

Rails.application.routes.draw do
  # ...all your other absolutely fabulous Workarea routes...
  mount Workarea::Api::Engine => '/api', as: :api

# ...except this one. Make sure it's last to correctly handle errors and redirects.
  mount Workarea::Storefront::Engine => '/', as: :storefront
end

Or, a subdomain. To use a subdomain for your API, create a file at app/routing_constraints/api_subdomain_constraint.rb with the following contents:

class ApiSubdomainConstraint
  def self.matches?(request)
    request.subdomain =~ /^api/
  end
end

Then, wrap your mount statement with a constraints block:

constraints ApiSubdomainConstraint do
  mount Workarea::Api::Engine => '/', as: :api
end

That will allow clients to access your API at https://api.yourtotallyamazingstore.com

If you use a routing constraint for your API, be sure to add the following to test/test_helper.rb in your application to use the correct domain for API requests:

class Workarea::IntegrationTest
  setup do
    host! host.gsub(/www/, 'api') if self.class.name.include?('Api::')
  end
end

Configuration

This plugin provides a number of options for configuring its usage...

config.api_product_image_jobs_blacklist configures the Dragonfly processor jobs whose URLs are omitted from image JSON responses in the Storefront API. Default is :convert, :encode, :rotate, :optim, :avatar, and :thumb.
config.authentication_token_expiration sets how long Storefront API auth tokens last before they are expired. Default is 1.week
config.max_api_bulk_data_size configures the max amount of items which may be included in a Workarea::Api::Admin::BulkUpsert
config.api_admin_ignore_definitions prevents certain models from being considered when Swagger JSON is being generated

Documentation

Documentation for API endpoints is available wherever the Workarea::Api::Engine has been mounted, at the relative path /docs. By default, this path is /api/docs. This documentation is loaded from the gem source by default, but if you customize API endpoints, you'll need to generate customized documentation with the following command:

GENERATE_API_DOCS=true bin/rails workarea:test

Documentation for the API is built using documentation tests, which describe how each controller and action is to be documented. Look in the aforementioned link to see some examples of documentation built using the documentation tests.