power_api 0.2.0 → 2.0.2

data/README.md

@@ -1,7 +1,7 @@
 # Power API
 
 [![Gem Version](https://badge.fury.io/rb/power_api.svg)](https://badge.fury.io/rb/power_api)
-[![Build Status](https://travis-ci.org/platanus/power_api.svg?branch=master)](https://travis-ci.org/platanus/power_api)
+[![CircleCI](https://circleci.com/gh/platanus/power_api.svg?style=shield)](https://app.circleci.com/pipelines/github/platanus/power_api)
 [![Coverage Status](https://coveralls.io/repos/github/platanus/power_api/badge.svg?branch=master)](https://coveralls.io/github/platanus/power_api?branch=master)
 
 It's a Rails engine that gathers a set of gems and configurations designed to build incredible REST APIs.
@@ -21,31 +21,36 @@ These gems are:
 
 ## Content
 
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Initial Setup](#initial-setup)
-    - [Command Options](#command-options)
-      - [--authenticated-resources](#--authenticated-resources)
-  - [Version Creation](#version-creation)
-  - [Controller Generation](#controller-generation)
-    - [Command Options](#command-options-1)
-      - [--attributes](#--attributes)
-      - [--controller-actions](#--controller-actions)
-      - [--version-number](#--version-number)
-      - [--use-paginator](#--use-paginator)
-      - [--allow-filters](#--allow-filters)
-      - [--authenticate-with](#--authenticate-with)
-      - [--owned-by-authenticated-resource](#--owned-by-authenticated-resource)
-      - [--parent-resource](#--parent-resource)
-- [Inside the gem](#inside-the-gem)
-  - [The Api::Error Concern](#the-apierror-concern)
-  - [The Api::Deprecated Concern](#the-apideprecated-concern)
-  - [The Api::Versioned Concern](#the-apiversioned-concern)
-  - [The ApiResponder](#the-apiresponder)
-- [Testing](#testing)
-- [Contributing](#contributing)
-- [Credits](#credits)
-- [License](#license)
+- [Power API](#power-api)
+  - [Content](#content)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Initial Setup](#initial-setup)
+    - [Exposed API mode](#exposed-api-mode)
+      - [Command options:](#command-options)
+        - [`--authenticated-resources`](#--authenticated-resources)
+    - [Internal API mode](#internal-api-mode)
+    - [Version Creation (exposed mode only)](#version-creation-exposed-mode-only)
+    - [Controller Generation (exposed and internal modes)](#controller-generation-exposed-and-internal-modes)
+      - [Command options (valid for internal and exposed modes):](#command-options-valid-for-internal-and-exposed-modes)
+        - [`--attributes`](#--attributes)
+        - [`--controller-actions`](#--controller-actions)
+        - [`--version-number`](#--version-number)
+        - [`--use-paginator`](#--use-paginator)
+        - [`--allow-filters`](#--allow-filters)
+        - [`--authenticate-with`](#--authenticate-with)
+        - [`--owned-by-authenticated-resource`](#--owned-by-authenticated-resource)
+        - [`--parent-resource`](#--parent-resource)
+  - [Inside the gem](#inside-the-gem)
+    - [The `Api::Error` concern](#the-apierror-concern)
+    - [The `Api::Deprecated` concern](#the-apideprecated-concern)
+    - [The `ApiResponder`](#the-apiresponder)
+    - [The `PowerApi::ApplicationHelper#serialize_resource` helper method](#the-powerapiapplicationhelperserialize_resource-helper-method)
+  - [Testing](#testing)
+  - [Publishing](#publishing)
+  - [Contributing](#contributing)
+  - [Credits](#credits)
+  - [License](#license)
 
 ## Installation
 
@@ -86,30 +91,13 @@ After doing this you will get:
   class Api::BaseController < PowerApi::BaseController
   end
   ```
-  Here you should include everything common to all your API versions. It is usually empty because most of the configuration comes in the `PowerApi::BaseController` that es inside the gem.
-
-- A base controller for the first version of your API under `/your_api/app/controllers/api/v1/base_controller.rb`
-  ```ruby
-  class Api::V1::BaseController < Api::BaseController
-    before_action do
-      self.namespace_for_serializer = ::Api::V1
-    end
-  end
-  ```
-  Everything related to version 1 of your API must be included here.
+  Here you should include everything common to all your APIs. It is usually empty because most of the configuration comes in the `PowerApi::BaseController` that is inside the gem.
 
 - Some initializers:
   - `/your_api/config/initializers/active_model_serializers.rb`:
     ```ruby
-    class ActiveModelSerializers::Adapter::JsonApi
-      def self.default_key_transform
-        :unaltered
-      end
-    end
-
-    ActiveModelSerializers.config.adapter = :json_api
+    ActiveModelSerializers.config.adapter = :json
     ```
-    Here we tell AMS that we will use the [json api](https://jsonapi.org/) format.
 
   - `/your_api/config/initializers/api_pagination.rb`:
     ```ruby
@@ -121,6 +109,30 @@ After doing this you will get:
     ```
     We use what comes by default and kaminari as pager.
 
+After running the installer you must choose an API mode.
+### Exposed API mode
+
+Use this mode if your API will be accessed by multiple clients or if your API is served somewhere other than your client application.
+
+You must run the following command to have the exposed API mode configuration:
+
+```bash
+rails generate power_api:exposed_api_config
+```
+
+After doing this you will get:
+
+- A base controller for the first version of your API under `/your_api/app/controllers/api/exposed/v1/base_controller.rb`
+  ```ruby
+  class Api::Exposed::V1::BaseController < Api::BaseController
+    before_action do
+      self.namespace_for_serializer = ::Api::V1
+    end
+  end
+  ```
+  Everything related to version 1 of your API must be included here.
+
+- Some initializers:
   - `/your_api/config/initializers/rswag-api.rb`:
     ```ruby
     Rswag::Api.configure do |c|
@@ -194,7 +206,7 @@ After doing this you will get:
     }
   end
   ```
-- An empty directory indicating where you should put your serializers for the first version: `/your_api/app/serializers/api/v1/.gitkeep`
+- An empty directory indicating where you should put your serializers for the first version: `/your_api/app/serializers/api/exposed/v1/.gitkeep`
 - An empty directory indicating where you should put your API tests: `/your_api/spec/integration/.gitkeep`
 - An empty directory indicating where you should put your swagger schemas `/your_api/spec/swagger/v1/schemas/.gitkeep`
 
@@ -223,7 +235,39 @@ Running the above code will generate, in addition to everything described in the
   ```
 - The migration `/your_api/db/migrate/20200228173608_add_authentication_token_to_users.rb` to add the `authentication_token` to your users table.
 
-### Version Creation
+### Internal API mode
+
+Use this mode if your API and your client app will be served on the same place.
+
+You must run the following command to have the internal API mode configuration:
+
+```bash
+rails generate power_api:internal_api_config
+```
+
+After doing this you will get:
+
+- A base controller for your internal API under `/your_api/app/controllers/api/internal/base_controller.rb`
+  ```ruby
+  class Api::Internal::BaseController < Api::BaseController
+    before_action do
+      self.namespace_for_serializer = ::Api::Internal
+    end
+  end
+  ```
+  Anything shared by the internal API controllers should go here.
+
+- A modified `/your_api/config/routes.rb` file:
+  ```ruby
+  namespace :api, defaults: { format: :json } do
+    namespace :internal do
+    end
+  end
+  ```
+
+- An empty directory indicating where you should put your serializers: `/your_api/app/serializers/api/internal/.gitkeep`
+
+### Version Creation (exposed mode only)
 
 To add a new version you must run the following command:
 ```bash
@@ -236,7 +280,7 @@ rails g power_api:version 2
 
 Doing this will add the same thing that was added for version one in the initial setup but this time for the number version provided as parameter.
 
-### Controller Generation
+### Controller Generation (exposed and internal modes)
 
 To add a controller you must run the following command:
 ```bash
@@ -266,18 +310,29 @@ end
 after doing this you will get:
 
 - A modified `/your_api/config/routes.rb` file with the new resource:
-  ```ruby
-  Rails.application.routes.draw do
-    scope path: '/api' do
-      api_version(module: 'Api::V1', path: { value: 'v1' }, defaults: { format: 'json' }) do
-        resources :blogs
+  - Exposed mode:
+    ```ruby
+    Rails.application.routes.draw do
+      scope path: '/api' do
+        api_version(module: 'Api::V1', path: { value: 'v1' }, defaults: { format: 'json' }) do
+          resources :blogs
+        end
       end
     end
-  end
-  ```
-- A controller under `/your_api/app/controllers/api/v1/blogs_controller.rb`
+    ```
+  - Internal mode:
+    ```ruby
+    Rails.application.routes.draw do
+      namespace :api, defaults: { format: :json } do
+        namespace :internal do
+          resources :blogs
+        end
+      end
+    end
+    ```
+- A controller under `/your_api/app/controllers/api/exposed/v1/blogs_controller.rb`
   ```ruby
-  class Api::V1::BlogsController < Api::V1::BaseController
+  class Api::Exposed::V1::BlogsController < Api::Exposed::V1::BaseController
     def index
       respond_with Blog.all
     end
@@ -306,18 +361,22 @@ after doing this you will get:
 
     def blog_params
       params.require(:blog).permit(
+        :id,
         :title,
         :body,
       )
     end
   end
   ```
-- A serializer under `/your_api/app/serializers/api/v1/blog_serializer.rb`
+  > With internal mode the file path will be: `/your_api/app/controllers/api/internal/blogs_controller.rb` and the class name: `Api::Internal::BlogsController`
+
+- A serializer under `/your_api/app/serializers/api/exposed/v1/blog_serializer.rb`
   ```ruby
-  class Api::V1::BlogSerializer < ActiveModel::Serializer
+  class Api::Exposed::V1::BlogSerializer < ActiveModel::Serializer
     type :blog
 
     attributes(
+      :id,
       :title,
       :body,
       :created_at,
@@ -325,7 +384,10 @@ after doing this you will get:
     )
   end
   ```
-- A spec file under `/your_api/spec/integration/api/v1/blogs_spec.rb`
+  > With internal mode the file path will be: `/your_api/app/serializers/api/internal/blog_serializer.rb` and the class name: `Api::Internal::BlogSerializer`
+
+- A spec file under `/your_api/spec/integration/api/exposed/v1/blogs_spec.rb`
+  - Exposed mode:
   ```ruby
   require 'swagger_helper'
 
@@ -344,7 +406,7 @@ after doing this you will get:
           schema('$ref' => '#/definitions/blogs_collection')
 
           run_test! do |response|
-            expect(JSON.parse(response.body)['data'].count).to eq(expected_collection_count)
+            expect(JSON.parse(response.body)['blogs'].count).to eq(expected_collection_count)
           end
         end
       end
@@ -355,7 +417,7 @@ after doing this you will get:
         produces 'application/json'
         parameter(name: :blog, in: :body)
 
-        response '201', 'blog creaed' do
+        response '201', 'blog created' do
           let(:blog) do
             {
               title: 'Some title',
@@ -365,6 +427,16 @@ after doing this you will get:
 
           run_test!
         end
+
+        response '400', 'invalid attributes' do
+          let(:blog) do
+            {
+              title: nil
+            }
+          end
+
+          run_test!
+        end
       end
     end
 
@@ -405,6 +477,16 @@ after doing this you will get:
 
           run_test!
         end
+
+        response '400', 'invalid attributes' do
+          let(:blog) do
+            {
+              title: nil
+            }
+          end
+
+          run_test!
+        end
       end
 
       delete 'Deletes Blog' do
@@ -423,57 +505,203 @@ after doing this you will get:
       end
     end
   end
+
+  ```
+  - Internal mode:
+  ```ruby
+  require 'rails_helper'
+
+  describe 'Api::Internal::BlogsControllers', type: :request do
+    describe 'GET /index' do
+      let!(:blogs) { create_list(:blog, 5) }
+      let(:collection) { JSON.parse(response.body)['blogs'] }
+      let(:params) { {} }
+
+      def perform
+        get '/api/internal/blogs', params: params
+      end
+
+      before do
+        perform
+      end
+
+      it { expect(collection.count).to eq(5) }
+      it { expect(response.status).to eq(200) }
+    end
+
+    describe 'POST /create' do
+      let(:params) do
+        {
+          blog: {
+            title: 'Some title'
+          }
+        }
+      end
+
+      let(:attributes) do
+        JSON.parse(response.body)['blog'].symbolize_keys
+      end
+
+      def perform
+        post '/api/internal/blogs', params: params
+      end
+
+      before do
+        perform
+      end
+
+      it { expect(attributes).to include(params[:blog]) }
+      it { expect(response.status).to eq(201) }
+
+      context 'with invalid attributes' do
+        let(:params) do
+          {
+            blog: {
+              title: nil
+            }
+          }
+        end
+
+        it { expect(response.status).to eq(400) }
+      end
+    end
+
+    describe 'GET /show' do
+      let(:blog) { create(:blog) }
+      let(:blog_id) { blog.id.to_s }
+
+      let(:attributes) do
+        JSON.parse(response.body)['blog'].symbolize_keys
+      end
+
+      def perform
+        get '/api/internal/blogs/' + blog_id
+      end
+
+      before do
+        perform
+      end
+
+      it { expect(response.status).to eq(200) }
+
+      context 'with resource not found' do
+        let(:blog_id) { '666' }
+
+        it { expect(response.status).to eq(404) }
+      end
+    end
+
+    describe 'PUT /update' do
+      let(:blog) { create(:blog) }
+      let(:blog_id) { blog.id.to_s }
+
+      let(:params) do
+        {
+          blog: {
+            title: 'Some title'
+          }
+        }
+      end
+
+      let(:attributes) do
+        JSON.parse(response.body)['blog'].symbolize_keys
+      end
+
+      def perform
+        put '/api/internal/blogs/' + blog_id, params: params
+      end
+
+      before do
+        perform
+      end
+
+      it { expect(attributes).to include(params[:blog]) }
+      it { expect(response.status).to eq(200) }
+
+      context 'with invalid attributes' do
+        let(:params) do
+          {
+            blog: {
+              title: nil
+            }
+          }
+        end
+
+        it { expect(response.status).to eq(400) }
+      end
+
+      context 'with resource not found' do
+        let(:blog_id) { '666' }
+
+        it { expect(response.status).to eq(404) }
+      end
+    end
+
+    describe 'DELETE /destroy' do
+      let(:blog) { create(:blog) }
+      let(:blog_id) { blog.id.to_s }
+
+      def perform
+        get '/api/internal/blogs/' + blog_id
+      end
+
+      before do
+        perform
+      end
+
+      it { expect(response.status).to eq(200) }
+
+      context 'with resource not found' do
+        let(:blog_id) { '666' }
+
+        it { expect(response.status).to eq(404) }
+      end
+    end
+  end
+
   ```
-- A swagger schema definition under `/your_api/spec/swagger/v1/schemas/blog_schema.rb`
+- A swagger schema definition under `/your_api/spec/swagger/v1/schemas/blog_schema.rb` (only for exposed mode)
   ```ruby
   BLOG_SCHEMA = {
     type: :object,
     properties: {
-      id: { type: :string, example: '1' },
-      type: { type: :string, example: 'blog' },
-      attributes: {
-        type: :object,
-        properties: {
-          title: { type: :string, example: 'Some title', 'x-nullable': true },
-          body: { type: :string, example: 'Some body', 'x-nullable': true },
-          created_at: { type: :string, example: '1984-06-04 09:00', 'x-nullable': true },
-          updated_at: { type: :string, example: '1984-06-04 09:00', 'x-nullable': true }
-        },
-        required: [
-        ]
-      }
+      id: { type: :integer, example: 666 },
+      title: { type: :string, example: 'Some title' },
+      body: { type: :string, example: 'Some body' },
+      created_at: { type: :string, example: '1984-06-04 09:00', 'x-nullable': true },
+      updated_at: { type: :string, example: '1984-06-04 09:00', 'x-nullable': true },
+      portfolio_id: { type: :integer, example: 666, 'x-nullable': true }
     },
     required: [
-      :id,
-      :type,
-      :attributes
+      :title,
+      :body
     ]
   }
 
   BLOGS_COLLECTION_SCHEMA = {
     type: "object",
     properties: {
-      data: {
+      blogs: {
         type: "array",
         items: { "$ref" => "#/definitions/blog" }
       }
     },
     required: [
-      :data
+      :blogs
     ]
   }
 
   BLOG_RESOURCE_SCHEMA = {
     type: "object",
     properties: {
-      data: { "$ref" => "#/definitions/blog" }
+      blog: { "$ref" => "#/definitions/blog" }
     },
     required: [
-      :data
+      :blog
     ]
   }
   ```
-- An edited version of `your_api/api_example/spec/swagger/v1/definition.rb` with the schema definitions for the `Blog` resource.
+- An edited version of `your_api/api_example/spec/swagger/v1/definition.rb` with the schema definitions for the `Blog` resource. (only for exposed mode)
   ```ruby
   API_V1 = {
     swagger: '2.0',
@@ -490,7 +718,7 @@ after doing this you will get:
   }
   ```
 
-#### Command options:
+#### Command options (valid for internal and exposed modes):
 
 ##### `--attributes`
 
@@ -502,9 +730,9 @@ rails g power_api:controller blog --attributes=title
 
 When you do this, you will see permited_params, serializers, swagger definitions, etc. showing only the selected attributes
 
-For example, the serializer under `/your_api/app/serializers/api/v1/blog_serializer.rb` will show:
+For example, the serializer under `/your_api/app/serializers/api/exposed/v1/blog_serializer.rb` will show:
 ```ruby
-class Api::V1::BlogSerializer < ActiveModel::Serializer
+class Api::Exposed::V1::BlogSerializer < ActiveModel::Serializer
   type :blog
 
   attributes(
@@ -526,7 +754,7 @@ When you do this, you will see that only relevant code is generated in controlle
 For example, the controller would only include the `show` and `destroy` actions and wouldn't include the `blog_params` method:
 
 ```ruby
-class Api::V1::BlogSerializer < Api::V1::BaseController
+class Api::Exposed::V1::BlogController < Api::Exposed::V1::BaseController
   def show
     respond_with blog
   end
@@ -551,6 +779,8 @@ Use this option if you want to decide which version the new controller will belo
 rails g power_api:controller blog --version-number=2
 ```
 
+> Important! When working with exposed api you should always specify the version, otherwise the controller will be generated for the internal api mode.
+
 ##### `--use-paginator`
 
 Use this option if you want to paginate the index endpoint collection.
@@ -559,10 +789,10 @@ Use this option if you want to paginate the index endpoint collection.
 rails g power_api:controller blog --use-paginator
 ```
 
-The controller under `/your_api/app/controllers/api/v1/blogs_controller.rb` will be modified to use the paginator like this:
+The controller under `/your_api/app/controllers/api/exposed/v1/blogs_controller.rb` will be modified to use the paginator like this:
 
 ```ruby
-class Api::V1::BlogsController < Api::V1::BaseController
+class Api::Exposed::V1::BlogsController < Api::Exposed::V1::BaseController
   def index
     respond_with paginate(Blog.all)
   end
@@ -583,10 +813,10 @@ Use this option if you want to filter your index endpoint collection with [Ransa
 rails g power_api:controller blog --allow-filters
 ```
 
-The controller under `/your_api/app/controllers/api/v1/blogs_controller.rb` will be modified like this:
+The controller under `/your_api/app/controllers/api/exposed/v1/blogs_controller.rb` will be modified like this:
 
 ```ruby
-class Api::V1::BlogsController < Api::V1::BaseController
+class Api::Exposed::V1::BlogsController < Api::Exposed::V1::BaseController
   def index
     respond_with filtered_collection(Blog.all)
   end
@@ -623,13 +853,15 @@ rails g power_api:controller blog --authenticate-with=user
 When you do this your controller will have the following line:
 
 ```ruby
-class Api::V1::BlogsController < Api::V1::BaseController
+class Api::Exposed::V1::BlogsController < Api::Exposed::V1::BaseController
   acts_as_token_authentication_handler_for User, fallback: :exception
 
   # mode code...
 end
 ```
 
+> With internal mode a `before_action :authenticate_user!` statement will be added instead of `acts_as_token_authentication_handler_for` in order to work with devise gem directly.
+
 In addition, the specs under `/your_api/spec/integration/api/v1/blogs_spec.rb` will add tests related with authorization.
 
 ```ruby
@@ -651,7 +883,7 @@ rails g power_api:controller blog --authenticate-with=user --owned-by-authentica
 The controller will look like this:
 
 ```ruby
-class Api::V1::BlogsController < Api::V1::BaseController
+class Api::Exposed::V1::BlogsController < Api::Exposed::V1::BaseController
   acts_as_token_authentication_handler_for User, fallback: :exception
 
   def index
@@ -686,6 +918,7 @@ class Api::V1::BlogsController < Api::V1::BaseController
 
   def blog_params
     params.require(:blog).permit(
+      :id,
       :title,
       :body
     )
@@ -729,9 +962,9 @@ rails g power_api:controller comment --attributes=body --parent-resource=blog
 
 Running the previous code we will get:
 
-- The controller under `/your_api/app/controllers/api/v1/comments_controller.rb`:
+- The controller under `/your_api/app/controllers/api/exposed/v1/comments_controller.rb`:
   ```ruby
-  class Api::V1::CommentsController < Api::V1::BaseController
+  class Api::Exposed::V1::CommentsController < Api::Exposed::V1::BaseController
     def index
       respond_with comments
     end
@@ -768,6 +1001,7 @@ Running the previous code we will get:
 
     def comment_params
       params.require(:comment).permit(
+        :id,
         :body
       )
     end
@@ -829,7 +1063,6 @@ module PowerApi
   class BaseController < ApplicationController
     include Api::Error
     include Api::Deprecated
-    include Api::Versioned
 
     self.responder = ApiResponder
 
@@ -867,7 +1100,7 @@ This module is useful when you want to mark endpoints as deprecated.
 For example, if you have the following controller:
 
 ```ruby
-class Api::V1::CommentsController < Api::V1::BaseController
+class Api::Exposed::V1::CommentsController < Api::Exposed::V1::BaseController
   deprecate :index
 
   def index
@@ -882,10 +1115,6 @@ And then in your browser you execute: `GET /api/v1/comments`, you will get a `De
 
 This is useful to notify your customers that an endpoint will not be available in the next version of the API.
 
-### The `Api::Versioned` concern
-
-This module includes to your API responses the version of the API in a header. For example: `Content-Type: application/json; charset=utf-8; version=1`
-
 ### The `ApiResponder`
 
 It look like this:
@@ -908,6 +1137,28 @@ end
 
 As you can see, this simple [Responder](https://github.com/heartcombo/responders) handles the API response based on the HTTP verbs.
 
+### The `PowerApi::ApplicationHelper#serialize_resource` helper method
+
+This helper method is useful if you want to serialize ActiveRecord resources to use in your views. For example, you can do:
+
+```
+<pre>
+  <%= serialize_resource(@resource, @options) %>
+</pre>
+```
+
+To get:
+
+```
+{"id":1,"title":"lean","body":"bla","createdAt":"2022-01-08T18:15:46.624Z","updatedAt":"2022-01-08T18:15:46.624Z","portfolioId":null}
+```
+
+The `@resource` parameter must be an ActiveRecord instance (`ApplicationRecord`) or collection (`ActiveRecord_Relation`).
+
+The `@options` parameter must be a `Hash` and can contain the options you commonly use with Active Model Serializer gem (`fields`, `transform_key`, etc.) and some others:
+- `include_root`: to get something like: `{"id":1,"title":"lean"}` or `{"blog": {"id":1,"title":"lean"}}`.
+- `output_format`: can be `:hash` or `:json`.
+
 ## Testing
 
 To run the specs you need to execute, **in the root path of the gem**, the following command:
@@ -918,6 +1169,17 @@ bundle exec guard
 
 You need to put **all your tests** in the `/power_api/spec/dummy/spec/` directory.
 
+## Publishing
+
+On master/main branch...
+
+1. Change `VERSION` in `lib/power_api/version.rb`.
+2. Change `Unreleased` title to current version in `CHANGELOG.md`.
+3. Run `bundle install`.
+4. Commit new release. For example: `Releasing v0.1.0`.
+5. Create tag. For example: `git tag v0.1.0`.
+6. Push tag. For example: `git push origin v0.1.0`.
+
 ## Contributing
 
 1. Fork it
@@ -936,4 +1198,4 @@ Power API is maintained by [platanus](http://platan.us).
 
 ## License
 
-Power API is © 2019 platanus, spa. It is free software and may be redistributed under the terms specified in the LICENSE file.
+Power API is © 2022 platanus, spa. It is free software and may be redistributed under the terms specified in the LICENSE file.