Invoke through the REST API
The Golem REST API exposes two endpoints for invoking workers. See the OSS or Cloud Worker REST API reference for details. These endpoints provide a direct, low level API for calling the exported functions of the workers. They use a special JSON format for encoding WASM values and types. It is possible, and recommended, to create custom HTTP APIs for exposing workers to the world.
Endpoints
Invoke
The invoke
endpoint enqueues an invocation for the given worker and returns immediately.
POST /v1/components/{component_id}/workers/{worker_name}/invoke?function={function_name}
This POST request invokes the worker called worker_name
of the component identified by component_id
(a UUID), calling the function function_name
.
Read the function name syntax page to learn how the function names are mapped.
The body of the POST request must be a JSON object containing a single field called params
, which is an array of typed JSON values. The format of typed JSON values is described below.
Invoke and await
The invoke-and-await
endpoint enqueues an invocation for a given worker and then awaits its completion, returning the successful result value or failure in the response body.
POST /v1/components/{component_id}/workers/{worker_name}/invoke-and-await?function={function_name}
This POST request invokes the worker called worker_name
of the component identified by component_id
(a UUID), calling the function function_name
.
Read the function name syntax page to learn how the function names are mapped.
The body of the POST request must be a JSON object containing a single field called params
, which is an array of typed JSON values. The format of typed JSON values is described below.
The response body is a JSON object with a single field result
, containing the invoked function's result encoded as a typed JSON value.
Implicit worker and resource creation
If the invoked worker does not exist, it is automatically created by the invocation.
When using the resource constructor syntax (see the function name syntax page), if the resource with the given constructor parameters does not exist yet, it is automatically created by the invocation.
Typed JSON values
Typed JSON values are JSON objects with two fields:
typ
describes the type of the valuevalue
is the actual value
The invocation API requires type information beside the values.
Value format
Read the JSON-WAVE Mapping page to see how every WebAssembly value is encoded in JSON.
Getting the type
When constructing invocation requests, the easiest way to get the type part of the request body is to get the component metadata using the REST API:
GET /v1/components/{component_id}/latest
This request returns the metadata of the latest version of the component given by its identifier (a UUID). This metadata lists all the exported functions and their expected parameter types. These parameter types encode type information in the same format as the invocation API, so it is possible to copy them when constructing invocations.
Note that it is not recommended to do this dynamically; the client using the invocation API should target a specific component version, with parameter types known in advance.
Type format
The following OpenAPI fragment defines the exact format of the typ
fields:
AnalysedResourceMode:
type: string
enum:
- Owned
- Borrowed
AnalysedType:
discriminator:
propertyName: type
mapping:
Variant: "#/components/schemas/AnalysedType_TypeVariant"
Result: "#/components/schemas/AnalysedType_TypeResult"
Option: "#/components/schemas/AnalysedType_TypeOption"
Enum: "#/components/schemas/AnalysedType_TypeEnum"
Flags: "#/components/schemas/AnalysedType_TypeFlags"
Record: "#/components/schemas/AnalysedType_TypeRecord"
Tuple: "#/components/schemas/AnalysedType_TypeTuple"
List: "#/components/schemas/AnalysedType_TypeList"
Str: "#/components/schemas/AnalysedType_TypeStr"
Chr: "#/components/schemas/AnalysedType_TypeChr"
F64: "#/components/schemas/AnalysedType_TypeF64"
F32: "#/components/schemas/AnalysedType_TypeF32"
U64: "#/components/schemas/AnalysedType_TypeU64"
S64: "#/components/schemas/AnalysedType_TypeS64"
U32: "#/components/schemas/AnalysedType_TypeU32"
S32: "#/components/schemas/AnalysedType_TypeS32"
U16: "#/components/schemas/AnalysedType_TypeU16"
S16: "#/components/schemas/AnalysedType_TypeS16"
U8: "#/components/schemas/AnalysedType_TypeU8"
S8: "#/components/schemas/AnalysedType_TypeS8"
Bool: "#/components/schemas/AnalysedType_TypeBool"
Handle: "#/components/schemas/AnalysedType_TypeHandle"
type: object
oneOf:
- $ref: "#/components/schemas/AnalysedType_TypeVariant"
- $ref: "#/components/schemas/AnalysedType_TypeResult"
- $ref: "#/components/schemas/AnalysedType_TypeOption"
- $ref: "#/components/schemas/AnalysedType_TypeEnum"
- $ref: "#/components/schemas/AnalysedType_TypeFlags"
- $ref: "#/components/schemas/AnalysedType_TypeRecord"
- $ref: "#/components/schemas/AnalysedType_TypeTuple"
- $ref: "#/components/schemas/AnalysedType_TypeList"
- $ref: "#/components/schemas/AnalysedType_TypeStr"
- $ref: "#/components/schemas/AnalysedType_TypeChr"
- $ref: "#/components/schemas/AnalysedType_TypeF64"
- $ref: "#/components/schemas/AnalysedType_TypeF32"
- $ref: "#/components/schemas/AnalysedType_TypeU64"
- $ref: "#/components/schemas/AnalysedType_TypeS64"
- $ref: "#/components/schemas/AnalysedType_TypeU32"
- $ref: "#/components/schemas/AnalysedType_TypeS32"
- $ref: "#/components/schemas/AnalysedType_TypeU16"
- $ref: "#/components/schemas/AnalysedType_TypeS16"
- $ref: "#/components/schemas/AnalysedType_TypeU8"
- $ref: "#/components/schemas/AnalysedType_TypeS8"
- $ref: "#/components/schemas/AnalysedType_TypeBool"
- $ref: "#/components/schemas/AnalysedType_TypeHandle"
AnalysedType_TypeBool:
allOf:
- type: object
properties:
type:
example: Bool
type: string
enum:
- Bool
required:
- type
- $ref: "#/components/schemas/TypeBool"
AnalysedType_TypeChr:
allOf:
- type: object
properties:
type:
example: Chr
type: string
enum:
- Chr
required:
- type
- $ref: "#/components/schemas/TypeChr"
AnalysedType_TypeEnum:
allOf:
- type: object
properties:
type:
example: Enum
type: string
enum:
- Enum
required:
- type
- $ref: "#/components/schemas/TypeEnum"
AnalysedType_TypeF32:
allOf:
- type: object
properties:
type:
example: F32
type: string
enum:
- F32
required:
- type
- $ref: "#/components/schemas/TypeF32"
AnalysedType_TypeF64:
allOf:
- type: object
properties:
type:
example: F64
type: string
enum:
- F64
required:
- type
- $ref: "#/components/schemas/TypeF64"
AnalysedType_TypeFlags:
allOf:
- type: object
properties:
type:
example: Flags
type: string
enum:
- Flags
required:
- type
- $ref: "#/components/schemas/TypeFlags"
AnalysedType_TypeHandle:
allOf:
- type: object
properties:
type:
example: Handle
type: string
enum:
- Handle
required:
- type
- $ref: "#/components/schemas/TypeHandle"
AnalysedType_TypeList:
allOf:
- type: object
properties:
type:
example: List
type: string
enum:
- List
required:
- type
- $ref: "#/components/schemas/TypeList"
AnalysedType_TypeOption:
allOf:
- type: object
properties:
type:
example: Option
type: string
enum:
- Option
required:
- type
- $ref: "#/components/schemas/TypeOption"
AnalysedType_TypeRecord:
allOf:
- type: object
properties:
type:
example: Record
type: string
enum:
- Record
required:
- type
- $ref: "#/components/schemas/TypeRecord"
AnalysedType_TypeResult:
allOf:
- type: object
properties:
type:
example: Result
type: string
enum:
- Result
required:
- type
- $ref: "#/components/schemas/TypeResult"
AnalysedType_TypeS16:
allOf:
- type: object
properties:
type:
example: S16
type: string
enum:
- S16
required:
- type
- $ref: "#/components/schemas/TypeS16"
AnalysedType_TypeS32:
allOf:
- type: object
properties:
type:
example: S32
type: string
enum:
- S32
required:
- type
- $ref: "#/components/schemas/TypeS32"
AnalysedType_TypeS64:
allOf:
- type: object
properties:
type:
example: S64
type: string
enum:
- S64
required:
- type
- $ref: "#/components/schemas/TypeS64"
AnalysedType_TypeS8:
allOf:
- type: object
properties:
type:
example: S8
type: string
enum:
- S8
required:
- type
- $ref: "#/components/schemas/TypeS8"
AnalysedType_TypeStr:
allOf:
- type: object
properties:
type:
example: Str
type: string
enum:
- Str
required:
- type
- $ref: "#/components/schemas/TypeStr"
AnalysedType_TypeTuple:
allOf:
- type: object
properties:
type:
example: Tuple
type: string
enum:
- Tuple
required:
- type
- $ref: "#/components/schemas/TypeTuple"
AnalysedType_TypeU16:
allOf:
- type: object
properties:
type:
example: U16
type: string
enum:
- U16
required:
- type
- $ref: "#/components/schemas/TypeU16"
AnalysedType_TypeU32:
allOf:
- type: object
properties:
type:
example: U32
type: string
enum:
- U32
required:
- type
- $ref: "#/components/schemas/TypeU32"
AnalysedType_TypeU64:
allOf:
- type: object
properties:
type:
example: U64
type: string
enum:
- U64
required:
- type
- $ref: "#/components/schemas/TypeU64"
AnalysedType_TypeU8:
allOf:
- type: object
properties:
type:
example: U8
type: string
enum:
- U8
required:
- type
- $ref: "#/components/schemas/TypeU8"
AnalysedType_TypeVariant:
allOf:
- type: object
properties:
type:
example: Variant
type: string
enum:
- Variant
required:
- type
- $ref: "#/components/schemas/TypeVariant"