Interfacing

Since the underlying execution strategy for an action can be a command, a HTTP request, or a RPC call, each action MUST provide an interface for it to be executed:

HTTP

actions.$.http

An action MAY use the HTTP protocol to execute it's function.

actions:
  convert:
    http:
      port: 8080
      method: get
      path: /convert
      url: https://example.com/api/full/path/without/query/parameters
FieldDescription
methodRequired. The HTTP method to be used - one of get/post/put/delete/patch
portRequired. If specified, url MUST NOT be specified. The port on which the connection must be established (to your microservice)
pathRequired. If specified, url MUST NOT be specified. The path for this action to be executed
urlRequired. If specified, port and path MUST NOT be specified. To be used when your action invokes a resource which is external to your microservice. The URL specified MUST BE absolute (with the scheme, host, port, and path). No query parameters should be included in the URL. Path parameters may be used (eg: https://example.com/api/{apiVersion}/foo)
contentTypeThe Content-Type for the request body. If any of your arguments have the field in set to requestBody, they'll be encoded with this Content-Type specified

Platform to Server

In this communication method the Service's HTTP server MUST be already running and waiting for connections. The Platform will make HTTP requests to the server which results in a response body of data which the Platform would handle.

+------------+         +----------+
|            |         |          |
|  Platform  |         |  Server  |
|            |         |          |
+-----+------+         +-----+----+
      |                      |
      |  {"word": "hello"}   |
      | -------------------> |
      |                      |
      |    {"length": 5}     |
      | <------------------- |
      |                      |

Location of arguments in the HTTP request

All types of HTTP requests will apply arguments based on the value of in for that argument.

The below example shows a GET request with a query and path parameter.




 
 
 
 
 
 



 



actions:
  fetch_usd:
    arguments:
      units:
        type: int
        in: query
      currency:
        type: string
        in: path
    output:
       type: int
    http:
      port: 8080
      method: get
      path: /fetch_usd/{currency}
actions.$.arguments.$.in

In addition to the fields documented here, the following fields are required for interfacing via HTTP:

FieldDescription
inRequired. The location of this argument in the HTTP request. It MUST be one of query, requestBody, path, or header

Path parameters MUST be specified in the path

$ curl -X GET http://service:8080/fetch_usd/eur?units=100

This next example is a POST where data is passed via the body.




 
 
 
 
 
 







actions:
  fetch_usd:
    arguments:
      units:
        type: int
        in: requestBody
      currency:
        type: string
        in: requestBody
    output:
      type: int
    http:
      contentType: application/json
      method: post
      path: /convert
$ curl -X POST http://service:8080/path -H "Content-Type: application/json" -d '{"currency": "eur", "units": 100}'

RPC

actions.$.rpc

The Service MAY communicate via RPC.

The Service MUST define server and framework attributes.

rpc:
  port: 8080
  framework:
    grpc:
      version: 2
      proto:
        path: git@github-server:project/repo.git/path/to/api.proto # Any valid URI path can be used
  client:
    endpoint: service
    port: 8080
    tls: true

💡 Heads up!

TLS configuration is defined separately. See the authentication section for details.