API docs by RedoclyKAR (v1)
Download OpenAPI specification:Download
This document describes the RESTful APIs provided or assumed by the Kubernetes Application Runtime (KAR). It consists of two sets of APIs:
- The sidecar APIs are implemented by the KAR sidecar.
- The application component APIs are meant to be implemented by application components.
The sidecar APIs are divided into logical groups:
- Actors: APIs to invoke actor methods.
- Services: APIs to invoke service endpoints.
- Callbacks: APIs to await the response to an asynchronous actor or service invocation.
- Events: APIs to publish to event sinks or subscribe actors to event sources.
- Reminders: APIs to schedule future actor invocations.
- State: APIs to manage the persistent state of actors.
- System: APIs for controlling the KAR runtime mesh.
The application component APIs are divided into logical groups:
- Actor runtime: APIs invoked by the sidecar to manage actor instances hosted by the application component.
call
Invoke an actor method
Call invokes the methodName method of the
actor instance indicated by actorType and actorId.
The request body must be a (possibly zero-length) JSON array whose elements
are used as the actual parameters of the actor method.
The result of the call is the result of invoking the target actor method
unless the async or promise pragma header is specified. If the actor
method returns void or undefined, then a 204 - No Content reponse is returned.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| methodName required | string Example: computeMyResult The actor method to be invoked |
query Parameters
| session | string The session is an opaque string used by the KAR runtime to enable reentrancy for nested actor calls and to track caller-callee relationships for failure recovery |
header Parameters
| Pragma | string Optionally specify the |
Request Body schema: application/kar+json
A possibly empty array containing the arguments with which to invoke the target actor method.
Responses
Request samples
- Payload
[- { }
]subscriptions
Cancel all subscriptions
This operation cancels all subscriptions for the actor instance specified in the path. The number of subscriptions cancelled is returned as the result of the operation.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
Responses
subscriptions/id
Cancel a subscription
This operation cancels the subscription for the actor instance specified in the path.
If the subscription is successfully cancelled a 200 response with a body of 1 will be returned.
If the subscription is not found, a 404 response will be returned unless
the boolean query parameter nilOnAbsent is set to true. If nilOnAbsent
is sent to true the 404 response will instead be a 200 with a body containing 0.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| subscriptionID required | string The id of the specific subscription being targeted |
query Parameters
| nilOnAbsent | boolean Replace a REST-style |
Responses
subscriptions/id
Get a subscription
This operation returns the subscription for the actor instance specified in the path.
If there is no subscription with the id subscriptionId a 404 response will be returned
unless the boolean query parameter nilOnAbsent is set to true.
If nilOnAbsent is true the 404 response will be replaced with
a 200 response with a nil response body.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| subscriptionID required | string The id of the specific subscription being targeted |
query Parameters
| nilOnAbsent | boolean Replace a REST-style |
Responses
subscriptions/id
Subscribe to a topic
Subscribe the actor instance using the subscriptionId specified in the path as described by the data provided in the request body. If there is already a subscription for the target actor instance with the same subscriptionId, that existing subscription will be updated based on the request body. The operation will not return until after the actor instance is subscribed.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| subscriptionID required | string The id of the specific subscription being targeted |
Request Body schema: application/json
The request body describes the subscription
| contentType | string The expected MIME content type of the events that will be produced by this subscription If an explicit value is not provided, the default value of application/json+cloudevent will be used. |
| path | string The actor method to be invoked with each delivered event |
| topic | string The name of the topic being subscribed to |
Responses
Request samples
- Payload
{- "contentType": "application/json",
- "path": "processEvent",
- "topic": "string"
}topic
Creates or updates a given topic
Parameters are specified in the body of the post, as stringified JSON. No body passed causes a default creation.
Request Body schema: application/json
The request body describes the topic to be created
object | |
| numPartitions | integer <int32> |
| replicationFactor | integer <int16> |
Responses
Request samples
- Payload
{- "configEntries": {
- "property1": "string",
- "property2": "string"
}, - "numPartitions": 0,
- "replicationFactor": 0
}publish
Publish an event to a topic
The event provided as the request body will be published on topic.
When the operation returns successfully, the event is guaranteed to
eventually be published to the targeted topic.
path Parameters
| topic required | string The topic name |
Request Body schema: application/*
An arbitrary request body to publish unchanged to the topic
Responses
reminders/id
Cancel a reminder
This operation cancels the reminder for the actor instance specified in the path.
If the reminder is successfully cancelled a 200 response with a body of 1 will be returned.
If the reminder is not found, a 404 response will be returned unless
the boolean query parameter nilOnAbsent is set to true. If nilOnAbsent
is sent to true the 404 response will instead be a 200 with a body containing 0.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| reminderId required | string The id of the specific reminder being targeted |
query Parameters
| nilOnAbsent | boolean Replace a REST-style |
Responses
reminders/id
Get a reminder
This operation returns the reminder for the actor instance specified in the path.
If there is no reminder with the id reminderId a 404 response will be returned
unless the boolean query parameter nilOnAbsent is set to true.
If nilOnAbsent is true the 404 response will be replaced with
a 200 response with a nil response body.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| reminderId required | string The id of the specific reminder being targeted |
query Parameters
| nilOnAbsent | boolean Replace a REST-style |
Responses
reminders/id
Schedule a reminder
Schedule the reminder for the actor instance and reminderId specified in the path as described by the data provided in the request body. If there is already a reminder for the target actor instance and reminderId, that existing reminder's schedule will be updated based on the request body. The operation will not return until after the reminder is scheduled.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| reminderId required | string The id of the specific reminder being targeted |
Request Body schema: application/json
The request body describes the reminder to be scheduled
| data | object An optional parameter containing an arbitrary JSON value that will be provided as the
payload when the |
| path | string The path to invoke on the actor instance when the reminder is fired |
| period | string The optional period parameter is a string encoding a GoLang Duration that is used to create a periodic reminder. If a period is provided, then the reminder will be fired repeatedly by adding the period to the last fire time to compute a new TargetTime for the next invocation of the reminder. |
| targetTime | string <date-time> The time at which the reminder should first fire, specified as a string in an ISO-8601 compliant format |
Responses
Request samples
- Payload
{- "data": "{ msg: \"Hello Friend!\" }",
- "path": "sayHello",
- "period": "30s",
- "targetTime": "2019-08-24T14:15:22Z"
}call
Perform a DELETE on a service endpoint
Execute a DELETE operation on the path endpoint of service.
The result of performing a DELETE on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Responses
call
Perform a GET on a service endpoint
Execute a GET operation on the path endpoint of service.
The result of performing a GET on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Responses
call
Perform a HEAD on a service endpoint
Execute a HEAD operation on the path endpoint of service.
The result of performing a HEAD on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Responses
call
Perform an OPTIONS on a service endpoint
Execute an OPTIONS operation on the path endpoint of service.
The request body is passed through to the target endpoint.
The result of performing an OPTIONS on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Request Body schema: application/json
An arbitrary request body to be passed through unchanged to the target endpoint
Responses
Request samples
- Payload
{ }call
Perform a PATCH on a service endpoint
Execute a PATCH operation on the path endpoint of service.
The request body is passed through to the target endpoint.
The result of performing a PATCH on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Request Body schema: application/json
An arbitrary request body to be passed through unchanged to the target endpoint
Responses
Request samples
- Payload
{ }call
Perform a POST on a service endpoint
Execute a POST operation on the path endpoint of service.
The request body is passed through to the target endpoint.
The result of performing a POST on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Request Body schema: application/json
An arbitrary request body to be passed through unchanged to the target endpoint
Responses
Request samples
- Payload
{ }call
Perfrom a PUT on a service endpoint
Execute a PUT operation on the path endpoint of service.
The request body is passed through to the target endpoint.
The result of performing a PUT on the target service endpoint
is returned unless the async or promise pragma header is specified.
path Parameters
| service required | string The service name |
| path required | string Example: an/arbitrary/valid/pathSegment The target endpoint to be invoked by the operation |
header Parameters
| Pragma | string Optionally specify the |
Request Body schema: application/json
An arbitrary request body to be passed through unchanged to the target endpoint
Responses
Request samples
- Payload
{ }state
Perform a multi-element update operation on the actor's state
The state updates contained in the request body will be performed on the
actor instance indicated by actorType and actorId.
All removal operations will be performed first, then all update
operations will be performed.
The result of the operation will contain the number of state elements
removed and updated.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
Request Body schema: application/json
The request body describes the multi-element update operation to be performed
| removals | Array of strings |
object | |
object | |
object |
Responses
Request samples
- Payload
{- "removals": [
- "string"
], - "submapremovals": {
- "property1": [
- "string"
], - "property2": [
- "string"
]
}, - "submapupdates": {
- "property1": {
- "property1": { },
- "property2": { }
}, - "property2": {
- "property1": { },
- "property2": { }
}
}, - "updates": {
- "property1": { },
- "property2": { }
}
}state/key
Remove a single entry in an actor's state
The state of the actor instance indicated by actorType and actorId
will be updated by removing the entry for key.
The operation will not return until the state has been updated.
The result of the operation is 1 if an entry was actually removed and
0 if there was no entry for key.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
Responses
state/key
Get a single entry of an actor's state
The key entry of the state of the actor instance indicated by actorType and actorId
will be returned as the response body.
If there is no entry for key a 404 response will be returned
unless the boolean query parameter nilOnAbsent is set to true,
in which case a 200 reponse with a nil response body will be returned.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
query Parameters
| nilOnAbsent | boolean Replace a REST-style |
Responses
state/key
Check to see if single entry of an actor's state is defined
Check to see if the state of the actor instance indicated by actorType and actorId
contains an entry for key.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
Responses
state/key
Perform an operation on the actor map key
The operation indicated by the op field of the request body will be performed on the key map
of the actor instance indicated by actorType and actorId. The result of the
operation will be returned as the response body.
If there are no key/subkey entries in the actor instance, the operation
will be interpreted as being applied to an empty map.
The valid values for op are:
- clear: remove all entires in the key actor map
- get: get the entire key actor map
- keys: return a list of subkeys that are defined in the key actor map
- size: return the number of entries the key actor map
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
Request Body schema: application/json
The request body describes the submap operation to be performed
| op | string |
Responses
Request samples
- Payload
{- "op": "string"
}state/key
Update a single entry of an actor's state
The state of the actor instance indicated by actorType and actorId
will be updated by setting key to contain the JSON request body.
The operation will not return until the state has been updated.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
Responses
state/key/subkey
Remove a single entry in an actor's state
The state of the actor instance indicated by actorType and actorId, and key
will be updated by removing the entry for key/subkey.
The operation will not return until the state has been updated.
The result of the operation is 1 if an entry was actually removed and
0 if there was no entry for key.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
| subkey required | string The subkey |
Responses
state/key/subkey
Get a single entry of an actor's state
The key/subkey entry of the state of the actor instance indicated by actorType and actorId
will be returned as the response body.
If there is no entry for key/subkey a 404 response will be returned
unless the boolean query parameter nilOnAbsent is set to true,
in which case a 200 reponse with a nil response body will be returned.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
| subkey required | string The subkey |
Responses
state/key/subkey
Check to see if single entry of an actor's state is defined
Check to see if the state of the actor instance indicated by actorType and actorId
contains an entry for key/subkey.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
| subkey required | string The subkey |
Responses
state/key/subkey
Update a single entry of a sub-map of an actor's state
The map state of the actor instance indicated by actorType and actorId
will be updated by setting key/subkey to contain the JSON request body.
The operation will not return until the state has been updated.
The result of the operation is 1 if a new entry was created and 0 if an existing entry was updated.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| key required | string The key |
| subkey required | string The subkey |
Responses
actor deallocation
Deallocate the language-level state for the specified actor instance
The optional passivation/deactivation method for the actor type will be invoked. After it completes, the language-level storate for the actor instance will be released. After this operation is invoked, no more POST operations on this actor instance may be performed unless a GET is first performed to re-initialize the language-level state of the actor instance.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
Responses
actor allocation
Allocate the language-level state for the specified actor instance
Causes the language-level actor runtime to allocate storage for the actor instance and to invoke its initialization/activation method if one is provided. This operation must be successfully completed before any POST operations on this actor instance are performed.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
query Parameters
| session | string The session is an opaque string used by the KAR runtime to enable reentrancy for nested actor calls and to track caller-callee relationships for failure recovery |
Responses
actor invocation
Invoke an actor method of the specified actor instance
Invokes the actor method on the actor instance within the session specified in the path. The body of the request will contain the actual paramters on which to invoke the method.
path Parameters
| actorType required | string The actor type |
| actorId required | string The actor instance id |
| methodName required | string Example: computeMyResult The actor method to be invoked |
query Parameters
| session | string The session is an opaque string used by the KAR runtime to enable reentrancy for nested actor calls and to track caller-callee relationships for failure recovery |
Request Body schema: application/kar+json
A possibly empty array containing the arguments with which to invoke the target actor method.
Responses
Request samples
- Payload
[- { }
]