Getting Started

Creating a new project

To create a new Angus project make sure the angus gem is installed and run

angus new MyAwesomeApi

Much alike rails, this command will create the basic files needed to run your project. It prepares the structure so you can focus on developing.

The output will look like this:

  create  MyAwesomeApi
  create  MyAwesomeApi/definitions
  create  MyAwesomeApi/resources
  create  MyAwesomeApi/services
  create  MyAwesomeApi/Gemfile
  create  MyAwesomeApi/config.ru
  create  MyAwesomeApi/services/my_awesome_api.rb
  create  MyAwesomeApi/definitions/messages.yml
  create  MyAwesomeApi/definitions/representations.yml
  create  MyAwesomeApi/definitions/service.yml

A quick overview of the generated files

config.ru

This is a rack app, so the config.ru contains the basic configuration to start the rack server.

Gemfile

The Gemfile has entries for rake and angus to execute commands and start the server. Running bundle install will add all the dependencies needed.

my_awesome_api.rb

This the main class of the project and inherits from Angus::Base. It has a configure method where you need to register every resource you add to your project with register :my_resource

class MyAwesomeApi < Angus::Base
  def configure
    register :my_resource
  end
end

definitions/messages.yml

Is meant to contain the error messages you raise in the ruby code.

For example you could raise UnauthorizedError and you would need to add an entry in this file for angus to handle this exception. More

definitions/representations.yml

When adding a resource you will have a new file operations.yml with the associated actions for that resource as shown here. When you want to use a new element type in the json structure you need to define the representation of that element in representations.yml. More

definitions/service.yml

service:   'MywesomeApi'
code_name: 'awesome'
version:   '0.2'

service is just the name the service appears with on the Documentation.

code_name will affect the path under which the service is made available.

version also affects the path. This way you know exactly what version your code is running.

Creating a new resource

Make sure to cd MyAwesomeApi. As with any REST API, the resource is the main subject in Angus. To add a new resource and auto-generate the required code you can run:

angus scaffold post

This will generate the following output

   exist  resources
   exist  definitions
  create  resources/posts.rb
  create  definitions/posts/operations.yml
  insert  services/my_awesome_api.rb

Start the server with angus server, making sure you ran bundle install first.

You can now see the auto-generated documentation at: http://localhost:9292/MyAwesomeApi/doc/0.1/

And the api is accessible at: http://localhost:9292/MyAwesomeApi/api/0.1/

Now what you need to do is adjust the parameters for each action in definitions/posts/operations.yml.

And edit the ruby code in resources/posts.rb

Overwhelmed? Try a simpler example.