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
      conversionAttributes:
        type: object
        properties:  # Required if the type is object.
          decimals:
            type: int
    output:
      type: object
      properties:
        units:
          type: float
        currency:
          type: string

Overview

Within a named action, the following fields are available:

FieldDescription
helpRequired. A human friendly description for this action
argumentsOptional and required inputs the action has. Read more
outputRequired. Type of data that the action returns. Read more
http | rpc | formatRequired. How to call the action. Read more

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:

FieldDescription
helpA short description of the argument which can provide clarity to end user
typeRequired. The type of this argument. It must be one of object, int, float, string, list, map, boolean, enum, or any
propertiesIf the value for type is object, this field MUST be specified. These properties will be serialised according to the execution strategy specified (eg: for the http strategy, the fields under properties will be serialised based on the contentType specified). objects MAY be nested in other objects
inRequired. The location of this argument. Each execution strategy provides different possible values for this. For possible values, see Interfacing
requiredWhether this argument is required or not. The default value for this is false
defaultThe default value if not provided by the user (not available for types map or object)
patternRead more (for type: string only)
enumRead more (for type: enum only)
rangeRead more (for type: int|float only)

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

Lists

actions.$.arguments.$.list actions.$.events.$.arguments.$.list

The optional argument list must have a key elements with the type of its list elements.






 



actions:
  colorize:
    arguments:
      colors:
        type: list
        list:
          elements:
            type: int

This service argument must be a list of integers.

Maps

actions.$.arguments.$.map actions.$.events.$.arguments.$.map

The argument map must have the keys keys and values with the respective types of the map.






 





actions:
  colorize:
    arguments:
      colorMapping:
        type: map
        map:
          keys:
            type: string
          values:
            type: int

This service argument must be a map with string as keys and integers as value.

Objects

actions.$.arguments.$.properties actions.$.events.$.arguments.$.properties

The argument type object must have a properties entry.






 







actions:
  colorize:
    arguments:
      color:
        type: object
        properties:
          red:
            type: float
          green:
            type: float
          blue:
            type: float

Objects may be nested:






 










actions:
  create:
    arguments:
      user:
        type: object
        properties:
          name:
            type: string
          location:
            type: object
            properties:
              street:
                type: string
              postcode:
                type: string

Output

Outputs are what the action returns as its result.

An action MUST define it's output.

FieldDescription
typeThe type of output. It must be one of int, float, string, list, map, boolean, object, or any
contentTypeIf the type is specified as object, this MUST indicate the Content-Type of the response
propertiesA map of key: {Output} (only for object types)
actionsA map of action: {Action} that can be performed by this output (only for object types)

If there is no output then it must use output: none explicitly. output: none can also be used if the output should be ignored (e.g. for debug output).

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: none

  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.