Reference on building external components that can work with Earl
Reviewers
Intro
Earl supports external component implementation through an HTTP API. External components can register with Earl and implement similar features to features found in the Standard Library, or act as value generators, that provide data on their outputs independently(schedulers, timers, feed listeners, weather updates).
Example component
External Weather Component
In requests below, it will be assumed that Earl is listening on http://earl, while the component’s endpoint is at http://weather.
The component will be a weather service with one string input used for providing human-readable location.
It will have one output on which it will provide the temperature, automatically as it updates.
Conventions
Requests marked as W→E for requests originating from weather component and processed by Earl
Requests marked as E→W for requests originating from Earl and processed by the weather component
Registering with the Rules Engine
Before being able to do anything, external components need to register with Earl. Currently, we’re not exposing the API externally, so the components need to be deployed as any other internal service, and thus need no special authorization. In future, if we decide to let others build external components(Partners, Makers), the flow will be augmented with authorization.
Types aren’t enforced at the moment, but inputs marked as required are treated appropriately.
Response
CREATED 201
Instancing
Each time an external component is instanced in rules, Earl needs to ask the component to provide that instance. This helps the engine route the values received from components to appropriate instances, and also enables referencing the instance when sending inputs to the component.
Intro
Example component
Conventions
Registering with the Rules Engine
W→E Request
POST http://earl/components
{
"name": "Weather",
"inputs": {
"location": {
"description": "Human readable location",
"type": "string",
"required": true
}
},
"outputs": {
"temperature": {
"description": "Current temperature, updated hourly",
"type": "number"
}
},
"endpoint": "http://weather"
}
Response
CREATED 201
Instancing
E→W Request
POST http://weather/instances
Response
CREATED 201
{
"id": "something-unique"
}