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.
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.
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 APIyml1api/2 models/3 (shopify)/ # folder to organize Shopify models, doesn't modify API4 shopifyProduct/5 schema.gadget.ts6 actions/7 create.js8 update.js9 delete.js10 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) folderJavaScript// no namespace is added to the APIawait 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:
- Create a new folder that is a child of the
api/models
folder - 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 atapi/models
- the
shopifyProduct
model is added to theshopify
folder:
Example: adding a 'shopify' model namespaceyml1api/2 models/3 shopify/ # model namespace <- the folder that was created4 shopifyProduct/ # model API identifier5 schema.gadget.ts6 actions/7 create.js8 update.js9 delete.js10 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 pathawait api.shopify.shopifyProduct.findMany()
1query {2 shopify {3 shopifyProducts {4 edges {5 node {6 id7 title8 }9 }10 }11 }12}
// the 'shopify' namespace included in the API pathawait api.shopify.shopifyProduct.custom(...);
1mutation {2 shopify {3 customShopifyProduct(id: $id) {4 success5 errors6 shopifyProduct {7 id8 title9 }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 namespaceyml1api/2 models/3 shopify/ # model namespace4 protectedData/ # nested model namespace5 shopifyCustomer/ # model API identifier6 schema.gadget.ts7 actions/8 create.js9 update.js10 delete.js11 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 pathawait api.shopify.protectedData.shopifyCustomer.custom(...);
1mutation {2 shopify {3 protectedData {4 customShopifyProduct(id: $id) {5 success6 errors7 shopifyProduct {8 id9 title10 }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' namespaceyml1api/2 models/3 biz/ # shared namespace4 shopifyProduct/5 schema.gadget.ts6 actions/7 create.js # model action, JS example: `api.biz.shopifyProduct.create(...)`8 actions/9 biz/ # shared namespace10 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' namespaceJavaScript// the 'biz' namespace included in the API pathawait api.biz.bar();await api.biz.shopifyProduct.create();