# Actions

Defining actions is a way to organize which APIs are exposed and how they are used within an application or platform.

Properly defining actions can assist with the following:

• Service discovery
• Documentation
• Operational insight

Services MUST list actions that can be executed.

At a high level, services SHOULD define the following about themselves:

• Interface (HTTP/RPC/etc)
• Arguments
• Output

Example

Here's an action called convert which accepts units, from and to returning an object with two properties - units and currency.

actions:
  convert:
    help: Convert a currency into another currency
    http: # defining how to execute this action, more below
    arguments:
      units:
        type: number
      from:
        type: string
      to:
        type: string
    output:
      type: object
      properties:
        units:
          type: number
        currency:
          type: string

# Overview

Within a named action, the following fields are available:

# Arguments

Define the arguments (input data) that the action accepts.

An action MUST declare all arguments it accepts. Each argument, will have the following information about it:

Example

Here is an action called capitalize which accepts string and returns a string.

actions:
  capitalize:
    arguments:
      text:
        help: The string to capitalize.
        type: string
        in: requestBody
    http:
      method: post
      port: 8000
      path: /run/capitalize
      contentType: application/json
    output:
      type: string

$ curl -H "Content-Type: application/json" -d '{"text":"einstein"}' http://service:8000/run/capitalize
# Einstein

# Patterns

The argument color must match the regexp pattern.

actions:
  colorize:
    arguments:
      color:
        type: string
        pattern: '^\#?\w{6}$'

# Enums

The argument color must match one of the values under enum.

actions:
  colorize:
    arguments:
      color:
        type: enum
        enum:
        - red
        - blue
        - green

# Range

The argument threshold must be within a range.

actions:
  colorize:
    arguments:
      threshold:
        type: int
        range:  # default is no bounds for min and max
          min: 10
          max: 20

# Output

Outputs are what the action returns as its result.

An action MUST define it's output.

If there is no output then it must use output: null explicitly.

# Properties

A map of properties this object has defined.

actions:
  getAddress:
    ...
    output:
      type: object
      properties:
        lat:
          type: float
        long:
          type: float

The output of this action returns an object that has two properties that can be accessed: lat and long.

# Next Actions

An output MAY define other actions the user may perform.

The action may reference properties of its parent.

actions:
  like: &like
    arguments:
      tweetid:
        type: int
    output: null

  stream:
    events:
      tweet:
        output:
          properties:
            id:
              type: int
          actions:
            like: 
              <<: *like  # yaml feature to reuse a defined structure (see &like above)
              defaults:
                tweetid: id

Twitter streams tweets. Each tweet has an output of which has an action like. It utilizes the service's action like by setting the argument tweetid to the property id. See full example here.