Events

A Service MAY have an action that publishes events asynchronously. The Platform would subscribe to events and the Service will publish events back to the Platform.

Intended for webhooks, pubsub, user interactions and streaming IoT data.

Example Event Pubsub





 


















 





 






actions:
  user:
    help: Subscribe to user events
    events:
      signup:
        help: When a customer signs up
        http: &http
          port: 5000
          subscribe:
            path: /subscribe
            method: post
            contentType: application/json
          unsubscribe:
            path: /unsubscribe
            method: post
        output: &user
          type: object
          contentType: application/json
          properties:
            name:
              type: string
            email:
              type: string
      login:
        help: When a user logs in.
        http:
          <<: *http  # yaml magic to reuse the object declared above
        output: 
          <<: *user
      logout:
        help: When a user logs out.
        http:
          <<: *http
        output:
          <<: *user
  1. Subscribe. The Platform subscribes to an event by making a HTTP request to the Service.
# Platform to Service
POST http://SERVICE/subscribe {
  "id": "9a8b0ad3-9bc0-4af5-890f-75b9acacf3ab",
  "event": "signup",
  "endpoint": "https://CLIENT/signups",
  "data": { }  # This would be a map of arguments if the event has any.
}

The Service MUST store this subscription information. Here's a Python snippet depicting this:

subscriptions = {}

def subscribe(data):
    subscriptions[data['id']] = data
  1. Publish. A new event is ready to be published by the Service.

Here's a Python snippet which reads our previously declared subscriptions map:

def publish(event, data):
    for subscription in subscriptions:
        if subscription['event'] == event:
            # Make a HTTP POST request to subscription['endpoint']

The Service then makes a HTTP POST request to send the event to the Platform using the CloudEvents spec.

# Service to Platform
POST https://CLIENT/signups {
  "cloudEventsVersion" : "0.1",
  "eventType" : "com.user.signup",
  "source" : "/signup",
  "eventID" : "A234-1234-1234",
  "eventTime" : "2018-04-05T17:31:00Z",
  "contentType" : "text/json",
  "data" : {  # event data
    "name": "Steve",
    "email": "no-reply@microservice.guide"
  }
}

This allows the Platform to subscribe to many events. All subscriptions will have a unique destination to publish events.

Overview

FieldDescription
helpA human friendly description for this event
httpRequired. Define how the platform can subscribe and unsubscribe from events
FieldDescription
portThe port to make (un)subscribe requests to
subscribeRequired. Describing how to subscribe to the event
FieldDescription
pathA path used in the request url
methodHTTP method. E.g. post
contentTypeChoose how arguments are encoded when subscribing
unsubscribeDescribing how to unsubscribe to the event
FieldDescription
pathA path used in the request url
methodHTTP method. E.g. post or delete
contentTypeChoose how arguments are encoded when unsubscribing
argumentsRequired. Optional and required inputs the action has. Read more
outputRequired. Type of data that the action returns. Read more

Example Services

Below are a few services that publish events.

Arguments

actions.$.events.$.arguments

Subscribing to an event MAY include arguments which can be used to define certain parameters concerning the subscription. For example, filtering the content before the event is published.

See Action Arguments for details.

Output

actions.$.events.$.output

The event published to the Platform MUST include the output detailing the structure of the event data published.

See Action Output for details.