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.

Available in Gadget framework version 1.1+

API namespaces were added with Gadget framework version 1.1. If you're using an older version of Gadget, you'll need to upgrade your framework version to use model namespaces.

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.

Just want a folder without changing your API?

If you want to add a folder to organize models without changing your API, you can put the folder name in parentheses (). If you already have an app that uses the API client, this is a great way to organize your files and folders without changing your API.

For example, adding a (shopify) folder for all Shopify models:

Add a (shopify) folder to organize models without changing your API
yml
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(...)`

If you wanted to read shopifyProduct records, you would call:

Example JS client API call with a (shopify) folder
JavaScript
// 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
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:

Example: reading with a 'shopify' model 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}
Example: writing with a 'shopify' model namespace
// 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
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:

Example: API calls with a nested 'protectedData' model namespace
// 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
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
// the 'biz' namespace included in the API path
await api.biz.bar();
await api.biz.shopifyProduct.create();