workarea-api-admin 4.4.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fa92eaf4f9148dae8ffba798b4acd8af62d8bfffab4e7da7ea981ad47719334
+  data.tar.gz: 4240b7bb56d687a50a7849e865243aff1141b84405c8c1457f50fab3460bf38f
+SHA512:
+  metadata.gz: ce2bf523e985e185a72754db8620242dacd236e5f3b18d90bf982bbed7b408a804ca45a567034f1e654a6d21d97d13974848ebca41794cddabac3da58ba82ce9
+  data.tar.gz: 1543e6e42c32a73e3f96f2996eaaa4d74e4800b959302057f8a4cf25b04001413da98cc67ac22b01f8180cf00aa3818b088447d9a20b1c32cfa6e5513adafb8d

data/.gitignore

@@ -0,0 +1,12 @@
+.bundle/
+Gemfile.lock
+.sass-cache/
+log/*.log
+pkg/
+test/dummy/public/system/dragonfly
+test/dummy/db/*.sqlite3
+test/dummy/log/*.log
+test/dummy/tmp/
+test/dummy/.sass-cache
+**/.DS_Store
+docs/build

data/README.md

@@ -0,0 +1,82 @@
+# Workarea Admin API
+
+Part of the [Workarea API][], the Admin API is used for programmatic
+access to your Workarea application's data model. It's designed to be
+"auto-extending", so that when you add or change fields in your Workarea
+models, those fields will be available for use in the API. This part of
+the Workarea API is primarily used for external services integration,
+such as with order management systems, enterprise resource planners, or
+email service providers, and provides detailed order and shipping information
+to such systems.
+
+## Overview
+
+- [Swagger][] integration with an implementation of the API in [OAS 2.0][OpenAPI]
+- Basic CRUD actions for core Workarea models
+- Bulk "Upsert" functionality for importing multiple records in the same
+  HTTP `PATCH` request.
+
+## Getting Started
+
+To use this plugin, install the **workarea-api** gem.
+
+For more information on the API as a whole, and to learn how to set up
+the API plugin, consult the [main README][Workarea API].
+
+## Authentication
+
+The Admin API secures itself using basic HTTP authentication. It authenticates
+with the same email address and password used to login to the admin. You will
+also need the API access permissions enabled for your account. This can be done
+in the permissions tab of the user edit page in the admin. You can also do this
+in the Rails console by enabling the `api_access` field on the user:
+
+To make requests to the Admin API, ensure your user has API access
+permissions. This can be changed in the "Permissions" tab of the "Edit
+User" page in the admin, or within the `rails console` using the
+following code:
+
+```ruby
+Workarea::User.find_by_email('user@workarea.com').update!(api_access: true)
+```
+
+(**NOTE:** Super-admins will automatically have this access)
+
+The Admin API uses [HTTP Basic Authentication][] to authorize client
+requests, with the format `email:password`. You can provide these
+details in an `Authorization` header, encoded in Base64...
+
+```http
+Authorization: Basic eW91cnVzZXJAZXhhbXBsZS5jb206UGFzc3dvcmQhMQ==\n
+```
+
+Or, in the URL, with requests made like:
+
+https://youruser@example.com:Password!1@yourtotallyamazingstore.com/api/orders.json
+
+Unlike the Storefront API, all Admin API endpoints are protected behind
+authentication.
+
+## Swagger
+
+Workarea's Admin API implements the [OpenAPI][] Specification for
+integration with [Swagger][] tools, IPaaS solutions like [Cenit][] or
+[Boomi][], and anything else that speaks OpenAPI. This can be accessed
+at your API's `/api/admin/swagger.json` endpoint, for example
+https://youruser@example.com:Password!1@yourtotallyamazingstore.com/api/swagger.json.
+Point your Swagger client to this endpoint to be able to use and browse
+the Swagger documentation for our API.
+
+## Copyright & Licensing
+
+Copyright Workarea 2017-2019. All rights reserved.
+
+For licensing, contact [sales@workarea.com][].
+
+[Workarea API]: https://homebase.weblinc.com/plugins/workarea-api-admin
+[sales@workarea.com]: mailto:sales@workarea.com
+[HTTP Basic Authentication]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme
+[OpenAPI]: https://swagger.io/resources/open-api/
+[Swagger]: https://swagger.io
+[Cenit]: https://cenit.io
+[Boomi]: https://boomi.com

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+# Load the dummy app's rake tasks
+APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'

data/app/assets/images/workarea/api/admin/icons/api.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path d="M47.6 20.1c-7.5 1.2-13.2 7.6-13.2 15.4V41c0 1.4 1.1 2.5 2.5 2.5h26.4c1.4 0 2.5-1.1 2.5-2.5v-5.4c0-7.8-5.7-14.3-13.2-15.4V9.8c0-1.4-1.1-2.5-2.5-2.5s-2.5 1.1-2.5 2.5v10.3zM45.9 50.8c0-1.4-1.1-2.5-2.5-2.5s-2.5 1.1-2.5 2.5v5.8h-4.1c-1.4 0-2.5 1.1-2.5 2.5v5.4c0 7.8 5.7 14.3 13.2 15.4v10.4c0 1.4 1.1 2.5 2.5 2.5s2.5-1.1 2.5-2.5V79.9c7.5-1.2 13.2-7.6 13.2-15.4V59c0-1.4-1.1-2.5-2.5-2.5h-4.1v-5.8c0-1.4-1.1-2.5-2.5-2.5s-2.5 1.1-2.5 2.5v5.8h-8.2v-5.7z"/></svg>

data/app/controllers/workarea/api/admin/application_controller.rb

@@ -0,0 +1,73 @@
+module Workarea
+  module Api
+    module Admin
+      class ApplicationController < Workarea::ApplicationController
+        include CurrentRelease
+        include ::Swagger::Blocks
+
+        respond_to :json
+
+        before_action :current_user # to force HTTP basic auth
+        before_action :set_json_format
+        before_action { params.permit! }
+        around_action :audit_log
+
+        rescue_from Mongoid::Errors::DocumentNotFound, with: :handle_not_found
+        rescue_from Mongoid::Errors::Validations, with: :handle_invalid
+        rescue_from Mongoid::Errors::UnknownAttribute, with: :handle_unknown_attribute
+
+        def current_user
+          return @current_user if defined?(@current_user)
+
+          if user = authenticate_with_http_basic { |u, p| Api::Admin.authenticate(u, p) }
+            @current_user = user
+          else
+            request_http_basic_authentication
+          end
+        end
+
+        def sort_field
+          params[:sort_by].presence || :created_at
+        end
+
+        def sort_direction
+          if params[:sort_direction].in?(%w(asc desc))
+            params[:sort_direction]
+          else
+            :desc
+          end
+        end
+
+        private
+
+        def current_release_id
+          params[:release_id]
+        end
+
+        def set_json_format
+          request.format = :json
+        end
+
+        def handle_not_found(e)
+          payload = { params: e.params, problem: e.problem }
+          render json: payload, status: :not_found
+        end
+
+        def handle_invalid(e)
+          payload = { problem: e.summary, document: e.document }
+          render json: payload, status: :unprocessable_entity
+        end
+
+        def handle_unknown_attribute(e)
+          render json: e.as_json.slice('problem'), status: :unprocessable_entity
+        end
+
+        def audit_log
+          Mongoid::AuditLog.record(current_user) do
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/workarea/api/admin/categories_controller.rb

@@ -0,0 +1,305 @@
+module Workarea
+  module Api
+    module Admin
+      class CategoriesController < Admin::ApplicationController
+        before_action :find_category, except: [:index, :create, :bulk]
+
+        swagger_path '/categories' do
+          operation :get do
+            key :summary, 'All Categories'
+            key :description, 'Returns all categories from the system'
+            key :operationId, 'listCategories'
+            key :produces, ['application/json']
+
+            parameter do
+              key :name, :page
+              key :in, :query
+              key :description, 'Current page'
+              key :required, false
+              key :type, :integer
+              key :default, 1
+            end
+            parameter do
+              key :name, :sort_by
+              key :in, :query
+              key :description, 'Field on which to sort (see responses for possible values)'
+              key :required, false
+              key :type, :string
+              key :default, 'created_at'
+            end
+            parameter do
+              key :name, :sort_direction
+              key :in, :query
+              key :description, 'Direction for sort by'
+              key :type, :string
+              key :enum, %w(asc desc)
+              key :default, 'desc'
+            end
+
+            response 200 do
+              key :description, 'Categories'
+              schema do
+                key :type, :object
+                property :categories do
+                  key :type, :array
+                  items do
+                    key :'$ref', 'Workarea::Catalog::Category'
+                  end
+                end
+              end
+            end
+          end
+
+          operation :post do
+            key :summary, 'Create Category'
+            key :description, 'Creates a new category.'
+            key :operationId, 'addCategory'
+            key :produces, ['application/json']
+
+            parameter do
+              key :name, :body
+              key :in, :body
+              key :description, 'Category to add'
+              key :required, true
+              schema do
+                key :type, :object
+                property :category do
+                  key :'$ref', 'Workarea::Catalog::Category'
+                end
+              end
+            end
+
+            response 201 do
+              key :description, 'Category created'
+              schema do
+                key :type, :object
+                property :category do
+                  key :'$ref', 'Workarea::Catalog::Category'
+                end
+              end
+            end
+
+            response 422 do
+              key :description, 'Validation failure'
+              schema do
+                key :type, :object
+                property :problem do
+                  key :type, :string
+                end
+                property :document do
+                  key :'$ref', 'Workarea::Catalog::Category'
+                end
+              end
+            end
+          end
+        end
+
+        def index
+          @categories = Catalog::Category
+                          .all
+                          .order_by(sort_field => sort_direction)
+                          .page(params[:page])
+
+          respond_with categories: @categories
+        end
+
+        def create
+          @category = Catalog::Category.create!(params[:category])
+          respond_with(
+            { category: @category },
+            { status: :created,
+            location: category_path(@category.id) }
+          )
+        end
+
+        swagger_path '/categories/{id}' do
+          operation :get do
+            key :summary, 'Find Category by ID'
+            key :description, 'Returns a single category'
+            key :operationId, 'showCategory'
+
+            parameter do
+              key :name, :id
+              key :in, :path
+              key :description, 'ID of category to fetch'
+              key :required, true
+              key :type, :string
+            end
+
+            response 200 do
+              key :description, 'Category details'
+              schema do
+                key :type, :object
+                property :category do
+                  key :'$ref', 'Workarea::Catalog::Category'
+                end
+              end
+            end
+
+            response 404 do
+              key :description, 'Category not found'
+              schema do
+                key :type, :object
+                property :problem do
+                  key :type, :string
+                end
+                property :params do
+                  key :type, :object
+                  key :additionalProperties, true
+                end
+              end
+            end
+          end
+
+          operation :patch do
+            key :summary, 'Update a Category'
+            key :description, 'Updates attributes on a category'
+            key :operationId, 'updateCategory'
+
+            parameter do
+              key :name, :id
+              key :in, :path
+              key :description, 'ID of category to update'
+              key :required, true
+              key :type, :string
+            end
+
+            parameter do
+              key :name, :body
+              key :in, :body
+              key :required, true
+              schema do
+                key :type, :object
+                property :category do
+                  key :description, 'New attributes'
+                  key :'$ref', 'Workarea::Catalog::Category'
+                end
+              end
+            end
+
+            response 204 do
+              key :description, 'Category updated successfully'
+            end
+
+            response 422 do
+              key :description, 'Validation failure'
+              schema do
+                key :type, :object
+                property :problem do
+                  key :type, :string
+                end
+                property :document do
+                  key :'$ref', 'Workarea::Catalog::Category'
+                end
+              end
+            end
+
+            response 404 do
+              key :description, 'Category not found'
+              schema do
+                key :type, :object
+                property :problem do
+                  key :type, :string
+                end
+                property :params do
+                  key :type, :object
+                  key :additionalProperties, true
+                end
+              end
+            end
+          end
+
+          operation :delete do
+            key :summary, 'Remove a Category'
+            key :description, 'Remove a category'
+            key :operationId, 'removeCategory'
+
+            parameter do
+              key :name, :id
+              key :in, :path
+              key :description, 'ID of category to remove'
+              key :required, true
+              key :type, :string
+            end
+
+            response 204 do
+              key :description, 'Category removed successfully'
+            end
+
+            response 404 do
+              key :description, 'Category not found'
+              schema do
+                key :type, :object
+                property :problem do
+                  key :type, :string
+                end
+                property :params do
+                  key :type, :object
+                  key :additionalProperties, true
+                end
+              end
+            end
+          end
+        end
+
+        def show
+          respond_with category: @category
+        end
+
+        def update
+          @category.update_attributes!(params[:category])
+          respond_with category: @category
+        end
+
+        swagger_path '/categories/bulk' do
+          operation :patch do
+            key :summary, 'Bulk Upsert Categories'
+            key :description, 'Creates new categories or updates existing ones in bulk.'
+            key :operationId, 'upsertCategories'
+            key :produces, ['application/json']
+
+            parameter do
+              key :name, :body
+              key :in, :body
+              key :description, 'Array of categories to upsert'
+              key :required, true
+              schema do
+                key :type, :object
+                property :categories do
+                  key :type, :array
+                  items do
+                    key :'$ref', 'Workarea::Catalog::Category'
+                  end
+                end
+              end
+            end
+
+            response 204 do
+              key :description, 'Upsert received'
+            end
+          end
+        end
+
+        def bulk
+          @bulk = Api::Admin::BulkUpsert.create!(
+            klass: Catalog::Category,
+            data: params[:categories].map(&:to_h)
+          )
+
+          head :no_content
+        end
+
+        def destroy
+          @category.destroy
+          head :no_content
+        end
+
+        private
+
+        def find_category
+          @category = Catalog::Category.find(params[:id])
+        end
+      end
+    end
+  end
+end