Model API namespaces 

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

How model namespaces work 

Namespacing in Gadget is folder-based, and model namespaces are added by creating folders in the api/models 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 (shopify) folder to organize models without changing your API
yml
Copy
1api/
2  models/
3    (shopify)/ # folder to organize Shopify models, doesn't modify API
4      shopifyProduct/
5        schema.gadget.ts
6        actions/
7          create.js
8          update.js
9          delete.js
10          custom.js # JS example: `api.shopifyProduct.custom(...)`

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

Adding model namespaces 

Model namespaces group related models together, and modify the JS and GraphQL APIs used to call model actions.

To add a model namespace:

1. Create a new folder that is a child of the api/models folder
2. Add a model to the new folder

For example, if you wanted to add a shopify namespace that contains the shopifyProduct model:

• a shopify folder is created at api/models
• the shopifyProduct model is added to the shopify folder:

Example: adding a 'shopify' model namespace
yml
Copy
1api/
2  models/
3    shopify/ # model namespace <- the folder that was created
4      shopifyProduct/ # model API identifier
5        schema.gadget.ts
6        actions/
7          create.js
8          update.js
9          delete.js
10          custom.js # JS example: `api.shopify.shopifyProduct.custom(...)`

The shopify namespace is added to your API, and you can now call your model actions using this namespace:

// the 'shopify' namespace included in the API path
await api.shopify.shopifyProduct.findMany()

1query {
2  shopify {
3    shopifyProducts {
4      edges {
5        node {
6          id
7          title
8        }
9      }
10    }
11  }
12}

// the 'shopify' namespace included in the API path
await api.shopify.shopifyProduct.custom(...);

1mutation {
2  shopify {
3    customShopifyProduct(id: $id) {
4      success
5      errors
6      shopifyProduct {
7        id
8        title
9      }
10    }
11  }
12}

You can add multiple models to the same namespace, and add as many model namespaces as you like.

You can also nest model namespaces, however, you cannot nest one model within another model.

Nested model namespaces 

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

For example, a protectedData namespace can be added underneath a shopify namespace, which contains the shopifyCustomer model:

Example: a nested 'protectedData' model namespace
yml
Copy
1api/
2  models/
3    shopify/ # model namespace
4      protectedData/ # nested model namespace
5        shopifyCustomer/ # model API identifier
6          schema.gadget.ts
7          actions/
8            create.js
9            update.js
10            delete.js
11            custom.js # JS example: `api.shopify.protectedData.shopifyCustomer.custom(...)`

Now the shopifyCustomer model actions can be called using:

// the 'shopify' and 'protectedData' namespaces included in the API path
await api.shopify.protectedData.shopifyCustomer.custom(...);

1mutation {
2  shopify {
3    protectedData {
4      customShopifyProduct(id: $id) {
5        success
6        errors
7        shopifyProduct {
8          id
9          title
10        }
11      }
12    }
13  }
14}

Shared namespaces 

Models and global actions can share namespaces. For example, if you wanted to add a biz namespace that contains both a model's actions and a global 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();