feat: add call to endpoint & authenticators (#6)

Encourage the use of classes for endpoints.

Author: adamcooke

README.md

@@ -49,40 +49,23 @@ end
 
 The key thing to note here is that the `CoreAPI::Base` reference is provided as a string rather than the constant itself. You can provide the constant here but using a string will ensure that API can be reloaded in development when classes are unloaded.
 
-### Creating a controller and endpoint
+### Creating an endpoint
 
-A controller is a collection of actions (or endpoints) that will perform actions and return data as appropriate. An API can have as many controllers as you need and a controller can have as many endpoints as needed.
-
-Begin by creating a new `controllers` directory in your `app/apis/core_api` directory. Within that, add a file for your first controller. In this example, we'll make a controller for managing products and thus we'll call it the `Products` controller. This controller should inherit from `Rapid::Controller`.
+An endpoint is an action that can be invoked by your consumers. It might return a list, create an resource or anything that takes your fancy. Begin by creating a new `endpoints` director in your `app/apis/core_api` directory. We'll begin by making an endpoint that will simply return a list of products that we sell. Make a file called `product_list_endpoint.rb` in your new `endpoints` directory.
 
 ```ruby
 module CoreAPI
-  module Controllers
-    module Products < Rapid::Controller
+  module Endpints
+    class ProductListEndpoint < Rapid::Endpoint
 
-      name 'Products'
-      description 'Allows you to list & manages products in the product database'
+      name 'List products'
+      description 'Returns a list of all product names in our catalogue'
 
-    end
-  end
-end
-```
-
-As with the API, this is a very basic implementation of a controller. A controller isn't much use without an endpoint through so we can add an endpoint here.
+      field :product_names, [:string]
 
-```ruby
-module CoreAPI
-  module Controllers
-    module Products < Rapid::Controller
-
-      endpoint :list do
-        name 'List products'
-        description 'Returns a full list of products'
-        field :products, [:string]
-        action do
-          product_names = Products.all.map(&:name)
-          response.add_field :products, product_names
-        end
+      def call
+        product_names = Product.order(:name).pluck(:name)
+        response.add_field :product_names, product_names
       end
 
     end
@@ -92,19 +75,17 @@ end
 
 This is a very simple endpoint. Walking through each section...
 
-- Firstly, we define the name of the endpoint which, in this case, is `list`. This will be addressed as `products/list` when requests are made to it.
-
-- Then we define the name and description for it. This will appear in the schema & documentation.
+- We begin by defining the name and description for it. This will appear in the schema & documentation.
 
 - Then we add a field which we will expect to be returned when this action is invoked. In this case, we're creating a field called `products` and specifying that it will be an array of strings that will be returned.
 
-- Then we define an action which will actually be executed when this endpoint is executed. This action has access to the request and the response. The `request` object contains information about the request being made and the `response` object allows you to influence what is returned to the consumer.
+- Then we define the `call` method which will actually be executed when this endpoint is called. In here, you have access to the request and the response. The `request` object contains information about the request being made and the `response` object allows you to influence what is returned to the consumer.
 
-- Finally, we use `response.add_field` to add data for the `products` field that we defined earlier. In this case, an array of product names.
+- Finally, we use `response.add_field` to add data for the `product_names` field that we defined earlier. In this case, an array of product names.
 
 #### A note about types
 
-When you define a field (or an argument) you must define a `type`. A type is what type of object that the consumer can expect to receive (or the server will expect to receive in the case of arguments). A type can be provided as a symbol to reference a scalar or a class that inherits from `Rapid::Scalar` (for scalars), `Rapid::Object` (for objects), `Rapid::Enum` (for enums) or `Rapid::Polymorph` (for polymorphs).
+When you define a field (or an argument) you must define a `type`. A type is what type of object that the consumer can expect to receive (or is expected to send in the case of arguments). A type can be provided as a symbol to reference a known scaler, or a class that inherits from `Rapid::Scalar` (for scalars), `Rapid::Object` (for objects), `Rapid::Enum` (for enums) or `Rapid::Polymorph` (for polymorphs).
 
 The following scalars are built-in:
 
@@ -125,7 +106,7 @@ module CoreAPI
   class Base < Rapid::API
 
     routes do
-      get 'products', controller: Controllers::Products, endpoint: :list
+      get 'products', endpoint: Endpoints::ListProductsEndpoint
     end
 
   end
@@ -176,16 +157,22 @@ By default, Rapid will try to find a value for your fields by calling a method n
 Once you have created your object class, you will need to update your endpoint to reference the object.
 
 ```ruby
-endpoint :list do
+class ProductListEndpoint < Rapid::Endpoint
+
+  # ...
+
   field :products, [Objects::Product]
-  action do |request, response|
-    response.add_field :products, Products.all.to_a
+
+  def call
+    products = Product.order(:name)
+    response.add_field :products, products.to_a
   end
+
 end
 ```
 
 If you make the request now, you should receive an array of objects (hashes) rather than strings now.
 
 ## Further reading
 
-Take a look through the docs folder
+Take a look through the docs folder.

doc/arguments.md

@@ -7,10 +7,12 @@ Arguments are the name given to any input that is being provided by the consumer
 At the most basic an argument will likely be a scalar value (a string, integer, boolean etc...) and will be defined as so on an endpoint:
 
 ```ruby
-endpoint :create do
+class MyEndpoint < Rapid::Endpoint
+
   argument :name, :string, required: true
   argument :age, :integer, required: true
   argument :superhuman, :boolean
+
 end
 ```
 
@@ -29,11 +31,14 @@ The consumer will provide arguments in one of two ways usually - they'll be prov
 Arguments are available on the `request` object within the `action` block of an action. For example:
 
 ```ruby
-endpoint :create do
+class MyEndpoint < Rapid::Endpoint
+
   argument :name, :string, required: true
-  action do
+
+  def call
     request.arguments[:name] # => 'Adam'
   end
+
 end
 ```
 
@@ -42,11 +47,14 @@ end
 If you wish to receive an array of items from a consumer, you can specify that an argument is an array rather than a flat object.
 
 ```ruby
-endpoint :create do
+class MyEndpoint < Rapid::Endpoint
+
   argument :names, [:string]
+
   action do
     request.arguments[:names] # => ['Adam', 'Dave', 'Charlie']
   end
+
 end
 ```
 
@@ -56,22 +64,25 @@ Argument sets provide you with an option to define a set of multiple arguments t
 
 ```ruby
 class UserProperties < Rapid::ArgumentSet
+
   argument :name, :string, required: true
   argument :date_of_birth, :date
   argument :hair_color, :string
   argument :favourite_color, :string
   argument :favourite_number, :integer
+
 end
 
-class Users < Rapid::Controller
-  endpoint :create do
-    argument :user, UserProperties, required: true
-    action do
-      request.arguments[:user][:name]
-      # or...
-      request.arguments.dig(:user, :name)
-    end
+class MyEndpoint < Rapid::Endpoint
+
+  argument :user, UserProperties, required: true
+
+  action do
+    request.arguments[:user][:name]
+    # or...
+    request.arguments.dig(:user, :name)
   end
+
 end
 ```
 
@@ -123,18 +134,19 @@ class UserLookup < Rapid::LookupArgumentSet
 
 end
 
-class Users < Rapid::Controller
-  endpoint :info do
-    argument :user, UserLookup, required: true
-    action do
-      # This will return the plain set as a normal argument set would.
-      user_set = request.arguments[:user]
+class InfoEndpoint < Rapid::Endpoint
 
-      # Calling `resolve` on this will actually resolve the user to
-      # the object as defined by the resolver.
-      user = request.arguments[:user].resolve
-    end
+  argument :user, UserLookup, required: true
+
+  def call
+    # This will return the plain set as a normal argument set would.
+    user_set = request.arguments[:user]
+
+    # Calling `resolve` on this will actually resolve the user to
+    # the object as defined by the resolver.
+    user = request.arguments[:user].resolve
   end
+
 end
 ```
 

doc/authentication.md

@@ -24,7 +24,7 @@ module CoreAPI
       field :given_token, :string
     end
 
-    action do
+    def call
       given_token_string = request.headers['Authorization'].sub(/\ABearer /, '')
       token = APIToken.authenticate(given_token_string)
       if token.nil?
@@ -43,7 +43,7 @@ Let's take a look through this line by line:
 - Firstly, we define the name & description for the authenticator. This is used for documentation.
 - Next, we choose the type of authenticator. Rapid only currently supports `:bearer`. This is only used for documentation purposes as well.
 - Then, we define a potential error that this authenticator might raise. In this case, the API token provided may be invalid and we'll raise that error.
-- Finally, we define an action which will be invoked. This is responsible for setting the `request.identity` property or raising an error if authentication has failed. You don't **have** to set a `request.identity` if you don't wish (anonymous access?) but unless you raise an error in here the endpoint execution will continue.
+- Finally, we define the `call` method which will be invoked when the authenticator is used. This is responsible for setting the `request.identity` property or raising an error if authentication has failed. You don't **have** to set a `request.identity` if you don't wish (anonymous access?) but unless you raise an error in here the endpoint execution will continue.
 
 ## Applying to the API
 
@@ -55,7 +55,7 @@ module CoreAPI
 
     authenticator Authenticator
 
-    # ... other API bits like controllers
+    # ... routes, scopes etc...
 
   end
 end

doc/consuming.md

@@ -4,7 +4,7 @@ This document outlines the conventions used for consuming APIs built with Rapid.
 
 ## Requests
 
-The address of each API endpoint is made up from two parts - a controller name and an endpoint name. For example, a list of users would have a controller name of `users` and an endpoint name of `list`. This is sent to the API in the URL of the request. For example:
+Consumers can make requests to any resource provided by the API (and listed as a route).
 
 ```
 /api/v1/users/list

doc/endpoints.md

@@ -16,7 +16,8 @@ Endpoints are the main core of the framework and this is where the majority of t
 This is an example endpoint for reference purposes.
 
 ```ruby
-endpoint :update do
+class UpdateEndpoint < Rapid::Endpoint
+
   # Defines some details about this endpoint for documentation
   name 'Update user details'
   description 'Updates a user details with the new information'
@@ -41,10 +42,11 @@ endpoint :update do
   potential_error Errors::ValidationError
 
   # Defines the action that will run
-  action do
+  def call
     user = request.arguments[:user].resolve
     user.update!(request.arguments[:details].to_hash)
     response.add_field :user, user
   end
+
 end
 ```

doc/errors.md

@@ -34,27 +34,34 @@ Errors can be raised by calling `raise_error` and providing either the name of t
 This example shows how to raise a class-defined error. You should also provide any fields that are required for the error as shown below with `errors`.
 
 ```ruby
-endpoint :create do
+class ExampleEndpoint < Rapid::Endpoint
+
   potential_error Errors::ValidationError
-  action do
+
+  def call
+    # ...
     unless user.save
       raise_error Errors::ValidationError, errors: user.errors.full_messages
     end
   end
+
 end
 ```
 
 This example shows how to raise an inline error.
 
 ```ruby
-endpoint :example do
+class ExampleEndpoint < Rapid::Endpoint
+
   potential_error 'NotPermitted' do
     code :not_permitted
     http_status 406
   end
-  action do
+
+  def call
     raise_error 'NotPermitted'
   end
+
 end
 ```
 
@@ -64,6 +71,7 @@ If any exception occurs during your application lifecycle, it will be returned t
 
 ```ruby
 class ValidationError < Rapid::Error
+
   # We can define things as normal for the error...
   code :validation_error
   http_status 416
@@ -83,15 +91,20 @@ end
 This will only be caught if the `ValidationError` error has been specified as a potential error for the endpoint where the exception is raised. So, you need to make sure to specify these if you want exceptions to be caught automatically. An endpoint might look this like:
 
 ```ruby
-endpoint :create do
+class ExampleEndpoint < Rapid::Endpoint
+
   argument :user_id, :integer, required: true
   argument :properties, ArgumentSets::UserProperties, required: true
+
   field :user, Objects::User
+
   potential_error ValidationError
-  action do
+
+  def call
     user = User.find(request.arguments[:user_id])
     user.update!(request.arguments[:properties]) # Might raise the error here but will be caught
     response.add_field :user, user
   end
+
 end
 ```