Create Simple Component

Create a new component

As the first step to creating APIs using API gateway, let's create a simple component.

We recommend trying out this simple example first before moving to exposing any complex worker functions as http APIs

golem app new

Please follow the instructions in the interactive shell. Here is the example

Selected profile: local
> Application name: shopping-cart
> Select language for the new component Rust
> Select a template for the new component: minimal: Minimal component template for Rust with no dependencies
> Component Package Name: amazon:shopping-cart
> Add another component or create application? Create application

Make sure to start the golem server by doing the following. Use --clean if you want a complete clean environment

golem server run --clean

Before we start building the API definition, make sure to replace the contents of shopping-cart/components-rust/amazon-shopping-cart/wit/amazon-shopping-cart.wit with the following

package amazon:shopping-cart;
 
interface api {
 
  record product-item {
    product-id: string,
    name: string,
    price: f32,
    quantity: u32,
  }
 
  record order {
    order-id: string,
    items: list<product-item>,
    total: f32,
    timestamp: u64,
  }
 
  record order-confirmation {
    order-id: string,
  }
 
  variant checkout-result {
    error(string),
    success(order-confirmation),
  }
 
  initialize-cart: func(user-id: string);
 
  add-item: func(item: product-item);
 
  remove-item: func(product-id: string);
 
  update-item-quantity: func(product-id: string, quantity: u32);
 
  checkout: func() -> checkout-result;
 
  get-cart-contents: func() -> list<product-item>;
 
  force-commit: func(count: u8);
}
 
world shopping-cart {
  import golem:api/host@1.1.6;
 
  export api;
}

Implement the interface

Try to build the component

cd shopping-cart
golem app build

This should give you a compile time error, and that's because you haven't implemented the interface yet. The implementation details doesn't matter.

Once you fix the compilation errors, test the invocations using golem REPL

Test the invocations

cd shopping-cart
golem repl

If by any chance you have multiple components in the context, interactive shell would allow you to select a specific component and will be automatically deployed to the server.

Here is an example usage of REPL. Please take advantage of the auto-completes using tab key.

More documentation on the REPL can be found here.

>>> let worker = instance("worker")
()
 
>>> worker.add-item({product-id: "foo", name: "foo", price: 42, quantity: 42})
()
 
>>> worker.add-item({product-id: "foo", name: "foo", price: 42, quantity: 42})
()
 
>>> worker.get-cart-contents()
[{product-id: "foo", name: "foo", price: 42, quantity: 42}, {product-id: "foo", name: "foo", price: 42, quantity: 42}]
 
>>> worker.checkout()
success({order-id: "238738674"})

REPL is a great way to test the component and its functions, however note that it's a brand new feature and is experimental in nature.

With this we successfully tested the component functions either using golem REPL or golem worker commands. Now we can move to exposing these worker functions as http APIs

Making Custom APIs Expose Http APIs