Skip to content

Latest commit

 

History

History
293 lines (226 loc) · 7.92 KB

creating_apipie_commands.md

File metadata and controls

293 lines (226 loc) · 7.92 KB

Creating commands for RESTful API with ApiPie

CLIs bound to a REST API do simillar things for most of the resources. Typically there are CRUD actions that appear for nearly every resource. Actions differ with parameters accross resources but the operations remain the same.

Hammer is optimised for usage with ApiPie and generated API bindings and tries to reduce the effort neccessary for a command creation.

ApiPie and bindings

ApiPie is a documentation library for RESTful APIs. Unlike traditional tools ApiPie uses DSL for API descriptions. This brings many advantages. See its documentation for details.

Foreman comes with ruby bindings automatically generated from the information provided by ApiPie. Every resource (eg. Architecture, User) has it's own class with methods for each available action (e.g. create, show, index, destroy). Apart from that it contains also full API documentation with parameters for the actions. This allows to reuse the documentation on the client side for automatic option definition and to reduce the amount of custom code per CLI action.

ApiPie commands in Hammer

Hammer provides HammerCLI::Apipie::Command base class for apipie actions. The command class is single resource related and expect the resource and an action to be defined.

There's a simple DSL for that:

class ListCommand < HammerCLI::Apipie::Command
  # define resource and the action together
  resource :architectures, :index
end

# or

class ListCommand2 < HammerCLI::Apipie::Command
  # define them separately
  resource :architectures
  action :index
end

Options definition

When the resource-action pair is defined we can take advantage of automatic option definition. There's an option builder for apipie parameters pre-set in the apipie command's base class. You can read details about the option builder principles here.

class ListCommand < HammerCLI::Apipie::Command
  resource :architectures, :index

  build_options
end

If we plug the command into an existing command tree and check the help we will see there are four parameters defined from the ApiPie docs. Compare the result with online API documentation.

$ hammer architecture list -h
Usage:
    hammer architecture list [OPTIONS]

Options:
    --search SEARCH               filter results
    --order ORDER                 sort results
    --page PAGE                   paginate results
    --per-page PER_PAGE           number of entries per request
    -h, --help                    print help

It is possible to combine apipie options with custom ones. If the generated options don't suit your needs for any reason, you can always redefine them by hand or just skip them.

See following example.

class ListCommand < HammerCLI::Apipie::Command
  resource :architectures, :index

  # first created option takes precedence
  option '--search', 'QUERY', "search query"

  # use option :without to define what options should be skipped
  build_options :without => [:order]
end
hammer architecture list -h
Usage:
    hammer architecture list [OPTIONS]

Options:
    --page PAGE                   paginate results
    --per-page PER_PAGE           number of entries per request
    --search QUERY                search query
    -h, --help                    print help

Note that the --search description has changed and --order disappeared.

Automaticaly generated options reflect:

  • parameter names and descriptions
  • required parameters
  • parameter types - the only supported type is array, which is translated to option normalizer List

Status messages

Some commands are expected to print result of the API action. There are two class methods for setting success and failure messages. Messages are printed according to the HTTP status code the API returned.

success_message "The user has been created"
failure_message "Could not create the user"

Example 1: Create an architecture

class CreateCommand < HammerCLI::Apipie::Command
  command_name "create"
  resource :architectures, :create

  success_message "Architecture created"
  failure_message "Could not create the architecture"

  build_options
end
$ hammer architecture create -h
Usage:
    hammer architecture create [OPTIONS]

Options:
    --name NAME
    --operatingsystem-ids OPERATINGSYSTEM_IDS Operatingsystem ID’s
                                  Comma separated list of values.
    -h, --help                    print help

$ hammer architecture create
ERROR: option '--name' is required

See: 'hammer architecture create --help'

$ hammer architecture create --name test --operatingsystem-ids=1,2
Architecture created

$ hammer architecture create --name test
Could not create the architecture:
  Name has already been taken

Example 2: Show an architecture

class InfoCommand < HammerCLI::Apipie::Command
  command_name "info"
  resource :architectures, :show

  # It's a good practice to reuse output definition from list commands
  # and add more details. This helps avoiding duplicities.
  output ListCommand.output_definition do
    from "architecture" do
      field :operatingsystem_ids, "OS ids", Fields::List
      field :created_at, "Created at", Fields::Date
      field :updated_at, "Updated at", Fields::Date
    end
  end

  build_options
end
$ hammer architecture info -h
Usage:
    hammer architecture info [OPTIONS]

Options:
    --id ID
    -h, --help                    print help

$ hammer architecture info --id 1
Id:          1
Name:        x86_64
OS ids:      1, 3
Created at:  2013/06/08 18:53:56
Updated at:  2013/06/08 19:17:43

Tips

When you define more commands like we've shown above you find yourself repeating resource ... in every one of them. As the commands are usually grouped by the resource it is handy to extract the resource definition one level up to the encapsulating command.

 class Architecture < HammerCLI::Apipie::Command

    resource :architectures

    class ListCommand < HammerCLI::Apipie::Command
      action :index
      # ...
    end


    class InfoCommand < HammerCLI::Apipie::Command
      action :show
      # ...
    end

    # ...
  end

ApiPie resources are being looked up in the encapsulating classes and modules when the definition is missing in the command class. If they are not found even there the resource of the parent command is used at runtime. This is useful for context-aware shared commands.

The following example shows a common subcommand that can be attached to any parent which has a resource implementing the method add_tag. Please note that this example is fictitious. There are no tags in Foreman's architectures and users.

module Tags
  class AddTag < HammerCLI::Apipie::WriteCommand
    option '--id', 'ID', 'ID of the resource'
    option '--tag', 'TAG', 'Name of the tag to add'
    action :add_tag
    command_name 'add-tag'
  end
end

class Architecture < HammerCLI::Apipie::Command
  resource :architectures
  # ...
  include Tags
  autoload_subcommands
end

class User < HammerCLI::Apipie::Command
  resource ForemanApi::Resources::User
  # ...
  include Tags
  autoload_subcommands
end
$ hammer architecture add-tag -h
Usage:
    hammer architecture add-tag [OPTIONS]

Options:
    --id ID                       ID of the resource
    --tag TAG                     Name of the tag to add
    -h, --help                    print help

$ hammer user add-tag -h
Usage:
    hammer user add-tag [OPTIONS]

Options:
    --id ID                       ID of the resource
    --tag TAG                     Name of the tag to add
    -h, --help                    print help