Emi Actions

Actions is a crucial part of almost every software. Actions in empty basically functions, which get an input, and return output. They can be correspond to ‘controllers’ in traditional API development, each action is basically an endpoint. Actions also can be called from other contexts than http, for example from cli.

For most cases, actions help you to define ‘get’, ‘post’ … actions, as well as ‘reactive’ which is a websocket, and ‘sse’, which stands for server side event.

Defining actions overview

As mentioned in the general definitions, actions is a part of module, which is an array, and allows developer to define multiple actions, as items. Each action must have a name, and that’s basically enough for it to be compiled by different sub compilers in Emi project.

name: sampleModule
actions:
  - name: getSinglePost
    url: https://jsonplaceholder.typicode.com/posts/:id
    cliName: get-single-post
    method: get
    description: Get's an specific post from the endpoint
    out:
      fields:
        - name: userId
          type: int64
        - name: id
          type: int64
        - name: title
          type: string
        - name: body
          type: string
  - name: sampleSse
    url: http://localhost:3000/stream
    method: get
    description: SSE Sample
    out:
      fields:
        - name: message
          type: string
  - name: webSocketOrgEcho
    url: "wss://echo.websocket.org/.ws"
    method: reactive
    description: Websocket.org eco server, to send a json and recieve back
    in:
      fields:
        - name: firstName
          type: string
        - name: lastName
          type: string
    out:
      fields:
        - name: lastName
          type: string

Actions properties

Each action within a module needs to have a camel case name, and needs to be unique. The other properties are optional. Nevertheless, ‘in’, ‘out’, ‘method’ and ‘url’ are the most common properties of an action which you’ll set as a developer. Depending on your use case, you might not need all features, or they might not be used by the sub compilers. | Property | Type | Description | |----------|------|-------------| | name | string | General name of the action used for generating code and CLI commands | | cliName | string | Overrides the CLI action name if specified otherwise defaults to Name | | cliShort | string | Shortcut to be used along side of the cliName as a shorter alternative | | url | string | HTTP route of the action; if not specified the action is CLI-only | | method | string | HTTP method type including standard and Emi-specific methods | | binaryType | string | Text by default for websocket | | qs | array | Type-safe query parameters for CLI and HTTP requests | | description | string | Action description used in API specs and documentation | | in | undefined | Request body definition similar to HTTP request body | | out | undefined | Response body definition similar to HTTP response body |

Action methods

Emi allows for standard http methods, as well as some extra which will be converted to different protocols. Currently supported the actions and methods are the following: post, patch, put, get, delete, reactive. Calling for non-existing method, would resolve to http with the non-standard method.