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 durable workers

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 durable workers

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}

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.

Ephemeral workers

For ephemeral workers, as they get automatically created and only live for a single invocation, no worker name is needed in the URI. Otherwise the endpoints work the same:

POST /v1/components/{component_id}/invoke?function={function_name}
POST /v1/components/{component_id}/invoke-and-await?function={function_name}

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 value
value 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"

Invoke CLI