---
schema_version: "1"
id: d41e666af50b1157d8967fe394e2a2f01002286c9f11066b3aa732b4d35ff34d
title: Shared Components
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-components-references.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-components-references.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: d76d66957ddda8a0abc6128d1263527a2365a768e48427fe91f9a1faf09c5a57
products:
  - Composable Storefront
  - Salesforce APIs
---
# Shared Components

The following code summarizes the shared components that can be used for the `components` object in the API contract:

```yaml
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes: { list of available scopes }
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes: { list of available scopes }
    AmOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes: { list of available scopes }
        clientCredentials:
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes: { list of available scopes }
  parameters:
    siteId:
      name: siteId
      in: query
      description: The site of the current request.
      required: true
      schema:
        type: string
        minLength: 1
    locale:
      name: locale
      in: query
      description: The locale of the current request.
      required: false
      schema:
        type: string
        minLength: 1
```

After that, the individual entries can be reused at different places of the schema.

## Use of References

The OpenAPI specification allows the use of [JSON References](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03) in schema files [as described here](https://spec.openapis.org/oas/v3.0.0#reference-object). This avoids defining objects multiple times at different places in the schema, leading to files that are smaller and easier to maintain.

**important:** Contrary to OAS, Custom APIs **_only allow local references_**, that is, references to objects defined in the same schema file. Specifically, only such references are possible:

- `$ref: '#/components/parameters/sampleParam'`

However, remote and URL references like these are not possible:

- `$ref: '../other_schema.yaml#/components/parameters/sampleParam'`
- `$ref: 'https://www.example.org/other_schema.yaml#/components/parameters/sampleParam'`

**Example:** Using the system query parameter `siteId` via a reference:

```yaml
components:
  parameters:
    siteId:
      name: siteId
      in: query
      description: The site of the current request.
      required: true
      schema:
        type: string
        minLength: 1
```

```yaml
paths:
  /customers:
    get:
      summary: Get loyalty information for customer
      operationId: getLoyaltyInfo
      parameters:
        - $ref: "#/components/parameters/siteId"
```