Operation Definition

What are operations for?

To specify the actual REST api. Here you set the path, the HTTP method, elements in the uri and the expected body. This info is what angus also exposes as documentation when accessing the doc url (e.g.: /awesome/doc/0.1)

How do I define an operation?

Let's start with a very basic example. The index action for posts.

index:
  name: 'index'
  description: 'Get posts.'
  path: '/posts'
  method: 'get'

  uri:
    - element:
      description:

  request:
    - element: q
      description: Search query.
      required: false
      type: string

  response:
    - element: 'posts'
      description: 'Available posts'
      required: true
      elements_type: post

  messages:
    - key: UnauthorizedError

Then name of the action is index. This will make angus invoke the Posts#index method of the class defined in resources/posts. So any call made to /posts will invoke the index method and attempt return whatever is returned by that method.

Now let's slice into what each field inside of index is used for.

• name - used for autogenerating the documentation
• description - displayed in the documentation
• path - the path at which this action will be made available. (e.g.: /awesome/api/0.1/posts)
• method - the HTTP method required. You can use the same path with different HTTP methods for different actions in the resource. Like Rails also does you can use variables here (e.g. posts/:id).
• uri - When you require elements in the path you must indicate them here and add a description for the documentation. This field can be ignored if the path doesn't contain parameters.
• request - Specify what you expect in the body of the request, or in the url for a GET. Can be omitted.
• response - Specify what you will return in the body of the response.
• messages - Specify what exceptions your action in the resource may raise, which you don't need to catch, angus will handle them gracefully and return a proper message based on messages.yml. You can omit this if your code does not raise exceptions.

Request & Response

To handle the content for each you can specify children elements indicating

- element: name_of_the_element
  description: 'A description'
  required: true
  type: string

This part is identical to the representation except that it uses element instead of field. Take a look at how to define a representation to understand what the available options & types are.

In practice this will require the request body to have a json with a key indicated by element and a value for that key of type.

{ "name_of_the_element": "some string" }

Messages

If under certain circumstances you wish to return an error like 404, 403 this is the way to do it with angus. You need to define the message first. Then simply indicate for each action what message it might raise and angus will do the rest for you. Returning with the status and messages indicated in messages.yml.