Action API namespaces 

You can group related global actions (and models) by adding namespaces to your API. Namespaces allow you to organize your actions and give you more control over the shape of your generated JavaScript and GraphQL API.

How action namespaces work 

Namespacing in Gadget is folder-based, and action namespaces are added by creating folders in the api/actions directory. The folder name is used as the namespace in the generated API.

Namespaces can also be shared between actions and models, and nested.

Add a (notifications) folder to organize models without changing your API
yml
Copy
1api/
2  actions/
3    (notifications)/ # folder to organize actions, doesn't modify API
4      sendEmail.js # actions within folder, JS example: `api.sendEmail(...)`
5      sendSMS.js
6      sendSlack.js

Example JS client API call with a (notifications) folder
JavaScript
Copy
// no namespace is added to the API
await api.sendEmail();

Adding action namespaces 

Action namespaces are only supported for global actions.

Global action namespaces 

To create a new global action namespace:

1. Create a new folder that is a child of the api/actions folder
2. Add an action to the new folder

For example, to add a bar.js global action to a foo namespace:

• a foo folder is created at api/actions
• a bar.js global action is added to the foo folder

Example: adding a 'foo' global action namespace
yml
Copy
api/
  actions/
    foo/ # global action namespace
      bar.js # global action, JS example: `api.foo.bar(...)`

The bar action could then be called using:

// the 'foo' namespace included in the API path
await api.foo.bar(...);

1mutation {
2  foo {
3    bar {
4      success
5      errors
6      result
7    }
8  }
9}

Nested action namespaces 

Model and global action namespaces can be nested. To nest a namespace, add additional folders to an existing namespace folder.

For example, adding a biz namespace to a foo/bar.js global action:

• a biz folder is created at api/actions/foo
• the bar.js global action is added to the biz folder

Example: a nested 'biz' global action namespace
yml
Copy
api/
  actions/
    foo/ # global action namespace
      biz/ # nested global action namespace
        bar.js # global action, JS example: `api.foo.biz.bar(...)`

The bar global action could then be called using:

// the nested 'biz' namespace included in the API path
await api.foo.biz.bar(...);

1mutation {
2  foo {
3    biz {
4      bar {
5        success
6        errors
7        result
8      }
9    }
10  }
11}

Shared namespaces 

Global actions and models can share namespaces. For example, if you wanted to add a biz namespace that contains both a global action and a model's action:

Example: a shared 'biz' namespace
yml
Copy
1api/
2  models/
3    biz/ # shared namespace
4      shopifyProduct/
5        schema.gadget.ts
6        actions/
7          create.js # model action, JS example: `api.biz.shopifyProduct.create(...)`
8  actions/
9    biz/ # shared namespace
10      bar.js # global action, JS example: `api.biz.bar(...)`

The bar global action and shopifyProduct.create model action could then be called using the biz namespace:

Example: API calls with a shared 'bix' namespace
JavaScript
Copy
// the 'biz' namespace included in the API path
await api.biz.bar();
await api.biz.shopifyProduct.create();