# Model API namespaces [Framework v1.1.0+](https://docs.gadget.dev/guides/gadget-framework) 

You can group related models (and [actions](https://docs.gadget.dev/guides/actions/namespacing-global-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  between actions and models, and .

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:

```yml
// in Add a (shopify) folder to organize models without changing your API
api/
  models/
    (shopify)/ # folder to organize Shopify models, doesn't modify API
      shopifyProduct/
        schema.gadget.ts
        actions/
          create.js
          update.js
          delete.js
          custom.js # JS example: `api.shopifyProduct.custom(...)`
```

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

```typescript
// 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:

```yml
// in Example: adding a 'shopify' model namespace
api/
  models/
    shopify/ # model namespace <- the folder that was created
      shopifyProduct/ # model API identifier
        schema.gadget.ts
        actions/
          create.js
          update.js
          delete.js
          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:

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

```graphql
query {
  shopify {
    shopifyProducts {
      edges {
        node {
          id
          title
        }
      }
    }
  }
}
```

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

```graphql
mutation {
  shopify {
    customShopifyProduct(id: $id) {
      success
      errors
      shopifyProduct {
        id
        title
      }
    }
  }
}
```

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

You can also  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:

```yml
// in Example: a nested 'protectedData' model namespace
api/
  models/
    shopify/ # model namespace
      protectedData/ # nested model namespace
        shopifyCustomer/ # model API identifier
          schema.gadget.ts
          actions/
            create.js
            update.js
            delete.js
            custom.js # JS example: `api.shopify.protectedData.shopifyCustomer.custom(...)`
```

Now the `shopifyCustomer` model actions can be called using:

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

```graphql
mutation {
  shopify {
    protectedData {
      customShopifyProduct(id: $id) {
        success
        errors
        shopifyProduct {
          id
          title
        }
      }
    }
  }
}
```

## 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:

```yml
// in Example: a shared 'biz' namespace
api/
  models/
    biz/ # shared namespace
      shopifyProduct/
        schema.gadget.ts
        actions/
          create.js # model action, JS example: `api.biz.shopifyProduct.create(...)`
  actions/
    biz/ # shared namespace
      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:

```typescript
// the 'biz' namespace included in the API path
await api.biz.bar();
await api.biz.shopifyProduct.create();
```