sfcc-dev-mcp 1.0.15 → 1.0.19

package/docs/best-practices/scapi_custom_endpoint.md

@@ -1,963 +0,0 @@
-# Salesforce B2C Commerce: Custom SCAPI Endpoint Best Practices
-
-This guide provides a concise overview of best practices and examples for creating custom Salesforce Commerce API (SCAPI) endpoints in B2C Commerce Cloud.
-
-**IMPORTANT**: Before implementing custom SCAPI endpoints, consult the **Performance and Stability Best Practices** guide from this MCP server. Pay special attention to the external system integration guidelines, timeout requirements, and caching strategies for optimal endpoint performance.
-
-## 1. Authentication Methodologies for Custom SCAPI Endpoints
-
-Custom SCAPI endpoints leverage the Shopper Login and API Access Service (SLAS) for authentication and authorization. Understanding SLAS authentication flows is critical for secure endpoint implementation.
-
-### 1.1 Client Architecture Decision: Public vs. Private
-
-The most critical architectural decision is determining your client type, which dictates the entire authentication flow:
-
-#### Private Clients
-- **Capability**: Can securely store a `client_secret` on a server-side component
-- **Use Cases**: Backend-for-Frontend (BFF), full-stack web applications, server-to-server integrations
-- **Security Model**: Uses `client_secret` in Basic Authorization header for client authentication
-- **OAuth Grant Types**: 
-  - `client_credentials` (guest users, system operations)
-  - `authorization_code` (registered user authentication)
-
-#### Public Clients
-- **Capability**: Cannot securely store secrets (operates in untrusted environments)
-- **Use Cases**: PWA Kit storefronts, Single-Page Applications (SPAs), native mobile apps
-- **Security Model**: Uses Proof Key for Code Exchange (PKCE) for dynamic security
-- **OAuth Grant Types**: 
-  - `authorization_code_pkce` (all authentication scenarios)
-
-### 1.2 Security Best Practices
-
-#### Scope-Based Authorization in Custom Endpoints
-
-Always implement fine-grained authorization checks in your endpoint scripts:
-
-```javascript
-// In your custom endpoint script
-exports.getLoyaltyInfo = function () {
-    var customerId = request.getHttpParameterMap().get('c_customer_id').getStringValue();
-    
-    // CRITICAL: Verify the authenticated user can access this customer's data
-    if (request.user && request.user.profile) {
-        var authenticatedCustomerId = request.user.profile.customerNo;
-        
-        // Prevent privilege escalation
-        if (authenticatedCustomerId !== customerId) {
-            RESTResponseMgr.createError(403, "insufficient-privileges", 
-                "Access Denied", "Cannot access another customer's data").render();
-            return;
-        }
-    }
-    
-    // Continue with business logic...
-};
-```
-
-### 1.3 Client Configuration and Scope Management
-
-#### SLAS Client Configuration
-
-Configure clients using the SLAS Admin API or UI:
-
-```javascript
-// Example API call to create/update a SLAS client
-const clientConfig = {
-    "clientId": "your-client-id",
-    "name": "My Custom API Client",
-    "isPrivateClient": true, // or false for public clients
-    "secret": "secure-client-secret", // Only for private clients
-    "channels": ["your-site-id"],
-    "scopes": [
-        "sfcc.shopper-baskets-orders.rw",
-        "sfcc.shopper-myaccount.rw", 
-        "sfcc.shopper-products",
-        "c_read_loyalty", // Your custom scope
-        "c_write_loyalty"
-    ],
-    "redirectUri": [
-        "https://your-app.com/callback"
-    ]
-};
-```
-
-#### Custom Object Scopes
-
-For accessing custom objects via SCAPI, configure both the object and scope:
-
-1. **Define Custom Object** in Business Manager: `Administration > Site Development > Custom Object Types`
-2. **Add Scope** to SLAS client: `sfcc.shopper-custom-objects.{object-type-id}`
-
-```yaml
-# In your schema.yaml
-security:
-  - ShopperToken: [sfcc.shopper-custom-objects.StoreReview]
-```
-
-### 1.4 Authentication Flow Examples & Testing
-
-#### Private Client: Guest Token Flow (Client Credentials)
-
-For server-side applications using private clients:
-
-```bash
-# Get Guest Token
-wget --post-data="grant_type=client_credentials" \
-     --header="Authorization: Basic $(echo -n 'your-private-client-id:your-client-secret' | base64)" \
-     --header="Content-Type: application/x-www-form-urlencoded" \
-     -O token_response.json \
-     "https://your-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/f_ecom_your_org/oauth2/token"
-
-# Extract Token and Test API Call
-TOKEN=$(cat token_response.json | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
-wget --header="Authorization: Bearer $TOKEN" \
-     -O categories.json \
-     "https://your-shortcode.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_your_org/categories/root?siteId=your-site-id"
-```
-
-#### Public Client: PKCE Authentication Flow
-
-For browser-based applications using PKCE:
-
-```bash
-# Generate PKCE Challenge
-VERIFIER=$(openssl rand -base64 96 | tr -d '\n' | tr '/+' '_-' | tr -d '=')
-CHALLENGE=$(echo -n $VERIFIER | openssl dgst -binary -sha256 | openssl base64 -A | tr '/' '_' | tr '+' '-' | tr -d '=')
-
-# Get Authorization Code (returns redirect with usid and code)
-wget --server-response --spider \
-     "https://your-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/f_ecom_your_org/oauth2/authorize?redirect_uri=http://localhost:3000/callback&response_type=code&hint=guest&client_id=your-public-client-id&code_challenge=$CHALLENGE" \
-     2>&1 | grep -i location
-
-# Exchange Code for Token (extract usid and code from Location header)
-wget --post-data="client_id=your-public-client-id&channel_id=your-site-id&code_verifier=$VERIFIER&usid=your-usid&code=your-code&grant_type=authorization_code_pkce&redirect_uri=http://localhost:3000/callback" \
-     --header="Content-Type: application/x-www-form-urlencoded" \
-     -O pkce_token_response.json \
-     "https://your-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/f_ecom_your_org/oauth2/token"
-```
-
-### 1.5 Error Handling and Troubleshooting
-
-#### Common Authentication Errors
-
-| Error Code | Cause | Solution |
-|------------|-------|----------|
-| 401 Unauthorized | Invalid or expired token | Refresh token or re-authenticate |
-| 403 Forbidden | Valid token, missing scope | Check client scope configuration |
-| 400 Bad Request | Invalid PKCE parameters | Verify code_verifier/code_challenge |
-| 404 Not Found | Incorrect endpoint URL | Verify API registration and URL structure |
-
-#### Token Validation in Scripts
-
-```javascript
-// Validate token and extract user information
-function validateAndExtractUser() {
-    if (!request.user) {
-        RESTResponseMgr.createError(401, "unauthorized", 
-            "Authentication Required", "Valid token required").render();
-        return null;
-    }
-    
-    // For registered users
-    if (request.user.profile && request.user.profile.customerNo) {
-        return {
-            type: 'registered',
-            customerId: request.user.profile.customerNo,
-            email: request.user.profile.email
-        };
-    }
-    
-    // For guest users
-    return {
-        type: 'guest',
-        customerId: request.user.ID // Guest customer ID
-    };
-}
-```
-
-#### Accessing Customer Context in Headless APIs
-
-Even though SCAPI endpoints use JWT-based authentication without traditional sessions, you can still access the authenticated customer:
-
-```javascript
-// Access the current customer (works for both registered and guest users)
-exports.getCustomerInfo = function () {
-    var session = request.getSession();
-    var customer = session.getCustomer();
-    
-    if (!customer) {
-        RESTResponseMgr.createError(401, "unauthorized", 
-            "No Customer", "No authenticated customer found").render();
-        return;
-    }
-    
-    var customerData = {
-        isRegistered: customer.isRegistered(),
-        isAuthenticated: customer.isAuthenticated()
-    };
-    
-    // For registered customers, access profile information
-    if (customer.isRegistered() && customer.getProfile()) {
-        var profile = customer.getProfile();
-        customerData.customerId = profile.getCustomerNo();
-        customerData.email = profile.getEmail();
-        customerData.firstName = profile.getFirstName();
-        customerData.lastName = profile.getLastName();
-    } else {
-        // For guest customers
-        customerData.customerId = customer.getID();
-        customerData.isGuest = true;
-    }
-    
-    RESTResponseMgr.createSuccess(customerData).render();
-};
-
-exports.getCustomerInfo.public = true;
-```
-
-## 2. URL Structure and Endpoint Mapping
-
-Understanding how your OpenAPI schema translates to actual SCAPI endpoint URLs is crucial for both development and client integration.
-
-### 2.1 SCAPI URL Structure
-
-All custom SCAPI endpoints follow this standardized URL pattern:
-
-```
-https://{shortcode}.api.commercecloud.salesforce.com/custom/{api-name}/v{major-version}/organizations/{organization-id}{path}?{query-parameters}
-```
-
-**URL Components:**
-- **`{shortcode}`**: Your SFCC instance shortcode (e.g., `zzrf-001`, `my-company-dev`)
-- **`{api-name}`**: The directory name under `cartridge/rest-apis/` in your cartridge
-- **`v{major-version}`**: Automatically derived from `info.version` in your `schema.yaml` (e.g., "1.0.0" → "v1", "2.3.1" → "v2")
-- **`{organization-id}`**: Your SFCC organization ID (typically starts with `f_ecom_`)
-- **`{path}`**: The path defined in your OpenAPI schema
-- **`{query-parameters}`**: Query string parameters from your schema
-
-### 2.2 Schema-to-URL Mapping Examples
-
-#### Example 1: Simple Query Parameters
-
-**OpenAPI Schema Definition:**
-```yaml
-# File: int_product_api/cartridge/rest-apis/product-info/schema.yaml
-openapi: 3.0.0
-info:
-  title: Product Information API
-  version: "1.0.0"
-paths:
-  /products/{sku}:
-    get:
-      summary: Retrieves basic product information by SKU
-      operationId: getProductInfo
-      parameters:
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-            minLength: 1
-        - name: sku
-          in: path
-          required: true
-          schema:
-            type: string
-            minLength: 1
-```
-
-**Resulting Endpoint URL:**
-```
-https://{{shortcode}}.api.commercecloud.salesforce.com/custom/product-info/v1/organizations/{{organizationId}}/products/682875540326M?siteId=RefArchGlobal
-```
-
-**Complete Example:**
-```
-https://zzrf-001.api.commercecloud.salesforce.com/custom/product-info/v1/organizations/f_ecom_zzrf_001/products/682875540326M?siteId=RefArchGlobal
-```
-
-#### Example 2: Complex Query Parameters with Custom Attributes
-
-**OpenAPI Schema Definition:**
-```yaml
-# File: int_pricing_api/cartridge/rest-apis/pricing-api/schema.yaml
-openapi: 3.0.0
-info:
-  title: Advanced Pricing API
-  version: "1.2.0"  # Results in v1 URL
-paths:
-  /product-pricing/{productId}:
-    get:
-      summary: Retrieves comprehensive pricing information for a product SKU
-      description: |
-        Returns detailed pricing information for a given product including:
-        - Base price and promotional prices
-        - Available coupon-based promotions (without requiring coupon codes)
-        - Price ranges for master products
-        - Quantity-based pricing tiers
-      operationId: getProductPricing
-      parameters:
-        - name: siteId
-          in: query
-          required: true
-          description: Site identifier for the pricing context
-          schema:
-            type: string
-            minLength: 1
-        - name: productId
-          in: path
-          required: true
-          description: Product ID or SKU to get pricing for
-          schema:
-            type: string
-            minLength: 1
-        - name: c_quantity
-          in: query
-          required: false
-          description: Quantity for tiered pricing calculation (defaults to 1)
-          schema:
-            type: number
-            minimum: 1
-            default: 1
-        - name: c_currency
-          in: query
-          required: false
-          description: Currency code for price display (defaults to session currency)
-          schema:
-            type: string
-            pattern: '^[A-Z]{3}$'
-        - name: c_include_upcoming_promotions
-          in: query
-          required: false
-          description: Include upcoming promotions within next 24 hours
-          schema:
-            type: boolean
-            default: false
-```
-
-**Resulting Endpoint URL:**
-```
-https://{{shortcode}}.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/{{organizationId}}/product-pricing/product-123?siteId=your-site-id&c_quantity=2&c_include_upcoming_promotions=true
-```
-
-**Complete Example:**
-```
-https://your-shortcode.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/your-org-id/product-pricing/product-123?siteId=your-site-id&c_quantity=2&c_include_upcoming_promotions=true
-```
-
-#### Example 3: Nested Resource Paths
-
-**OpenAPI Schema Definition:**
-```yaml
-# File: int_customer_api/cartridge/rest-apis/customer-management/schema.yaml
-openapi: 3.0.0
-info:
-  title: Customer Management API
-  version: "2.0.0"  # Results in v2 URL
-paths:
-  /customers/{customerId}/orders/{orderId}/tracking:
-    get:
-      summary: Get order tracking information
-      operationId: getOrderTracking
-      parameters:
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-        - name: customerId
-          in: path
-          required: true
-          schema:
-            type: string
-        - name: orderId
-          in: path
-          required: true
-          schema:
-            type: string
-        - name: c_include_delivery_details
-          in: query
-          required: false
-          schema:
-            type: boolean
-            default: false
-```
-
-**Resulting Endpoint URL:**
-```
-https://{{shortcode}}.api.commercecloud.salesforce.com/custom/customer-management/v2/organizations/{{organizationId}}/customers/12345/orders/ORD-001234/tracking?siteId=SiteGenesis&c_include_delivery_details=true
-```
-
-### 2.3 Parameter Access in Scripts
-
-Understanding how to access different parameter types in your script implementation:
-
-```javascript
-'use strict';
-
-var RESTResponseMgr = require('dw/system/RESTResponseMgr');
-
-exports.getProductPricing = function () {
-    // Path parameters: use getSCAPIPathParameters()
-    var productId = request.getSCAPIPathParameters().get('productId');
-    
-    // Query parameters: use getHttpParameterMap()
-    var siteId = request.getHttpParameterMap().get('siteId').getStringValue();
-    var quantity = request.getHttpParameterMap().get('c_quantity').getIntValue() || 1;
-    var currency = request.getHttpParameterMap().get('c_currency').getStringValue();
-    var includeUpcoming = request.getHttpParameterMap().get('c_include_upcoming_promotions').getBooleanValue();
-    
-    // Parameter validation
-    if (!productId) {
-        RESTResponseMgr.createError(400, "missing-product-id", 
-            "Missing Product ID", "Product ID is required in the path").render();
-        return;
-    }
-    
-    // Business logic implementation...
-    var pricingData = {
-        productId: productId,
-        basePrice: 29.99,
-        salePrice: 24.99,
-        currency: currency || "USD",
-        quantity: quantity,
-        upcomingPromotions: includeUpcoming ? [] : undefined
-    };
-    
-    RESTResponseMgr.createSuccess(pricingData).render();
-};
-
-exports.getProductPricing.public = true;
-```
-
-### 2.4 Version Management in URLs
-
-The version segment in your URL is automatically determined by the major version number in your OpenAPI schema:
-
-| Schema Version | URL Version | Example URL |
-|----------------|-------------|-------------|
-| "1.0.0" | v1 | `/custom/my-api/v1/organizations/...` |
-| "1.2.5" | v1 | `/custom/my-api/v1/organizations/...` |
-| "2.0.0" | v2 | `/custom/my-api/v2/organizations/...` |
-| "2.1.3" | v2 | `/custom/my-api/v2/organizations/...` |
-| "3.0.0-beta" | v3 | `/custom/my-api/v3/organizations/...` |
-
-**Best Practice**: Use semantic versioning in your schema and introduce breaking changes only in new major versions to maintain backward compatibility.
-
-### 2.5 Testing Your URL Mappings
-
-#### Using Postman/cURL
-
-```bash
-# Test the product pricing endpoint
-curl -X GET \
-  'https://your-shortcode.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/your-org-id/product-pricing/product-123?siteId=your-site-id&c_quantity=2&c_include_upcoming_promotions=true' \
-  -H 'Authorization: Bearer YOUR_SLAS_TOKEN' \
-  -H 'Content-Type: application/json'
-```
-
-### 2.6 Common Issues and Solutions
-
-| Issue | Symptom | Solution |
-|-------|---------|----------|
-| 404 Not Found | Endpoint not accessible | Check cartridge registration, API directory name, and schema syntax |
-| Version mismatch | Wrong version in URL | Verify `info.version` in schema.yaml matches expected URL |
-| Parameter not found | Script can't access parameters | Ensure parameter names match schema exactly, use correct access method |
-| Invalid path structure | URL doesn't match expected pattern | Verify path definition in schema matches your intended URL structure |
-
-### 2.7 Documentation for Client Developers
-
-When documenting your custom endpoints for client developers, always provide:
-
-1. **Complete URL Examples**: Show the full URL with real values
-2. **Parameter Descriptions**: Explain what each parameter does and its format requirements
-3. **Authentication Requirements**: Specify required scopes and token types
-4. **Response Examples**: Include sample JSON responses
-5. **Error Scenarios**: Document common error codes and their meanings
-
-**Example Documentation:**
-
-```markdown
-## Get Product Pricing
-
-Retrieves comprehensive pricing information for a product.
-
-### Endpoint
-`GET /custom/pricing-api/v1/organizations/{organizationId}/product-pricing/{productId}`
-
-### Full URL Example
-```
-https://your-shortcode.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/f_ecom_your_org/product-pricing/ABC123?siteId=RefArchGlobal&c_quantity=2
-```
-
-### Parameters
-- `productId` (path, required): Product SKU or ID
-- `siteId` (query, required): Site identifier
-- `c_quantity` (query, optional): Quantity for tiered pricing (default: 1)
-- `c_currency` (query, optional): Currency code (default: session currency)
-
-### Authentication
-Requires SLAS Shopper Token with scope: `c_read_pricing`
-```
-
-This URL structure understanding is essential for both endpoint development and client integration, ensuring your custom SCAPI endpoints are accessible and properly documented.
-
-## 3. Securing Endpoints
-
-Endpoints must be associated with a security scheme in the API contract. SCAPI supports two primary security schemes for custom endpoints:
-
-- **ShopperToken**: For Shopper APIs and storefront use cases. Use Shopper Login and API Access to obtain tokens.
-- **AmOAuth2**: For SCAPI Admin APIs to be used with backoffice apps. Use Account Manager to obtain tokens.
-
-Association is either per operation or global, with the operation scheme taking precedence. The schemes are the same as those used for non-custom B2C Commerce APIs (SCAPI).
-
-The scheme must set exactly one custom scope.
-
-### 3.1 Security Scheme Configuration
-
-Schemes used in the contract must be defined in the components section, for example:
-
-```yaml
-components:
-  securitySchemes:
-    ShopperToken: {}
-    AmOAuth2:
-      type: oauth2
-
-# 👇 A global scheme applies to all operations in this file.
-security:
-  - AmOAuth2: ["c_loyalty_rw"]
-
-paths:
-  /customer:
-    get:
-      operationId: getLoyaltyInfo
-      parameters:
-        - in: query
-          name: siteId
-          required: true
-          schema:
-            type: string
-            minLength: 1
-      responses:
-        200:
-          description: OK
-      # 👇 An operation scheme applies only to this operation and takes precedence over the global scheme.
-      security:
-        - ShopperToken: ["c_loyalty"]
-```
-
-### 3.2 Custom Scope Requirements
-
-Custom scopes must meet the following requirements:
-
-- The name must begin with `c_`.
-- The name must not contain characters other than alphanumeric, period, hyphen and underscore.
-- The name must not be more than 25 characters.
-
-Endpoints without correct scheme or scope assignments are not registered.
-
-### 3.3 Requesting Endpoints
-
-#### ShopperLogin
-
-Scopes for ShopperLogin can be assigned to a client in the SLAS Admin UI. For example:
-
-> Custom API SLAS scope configuration and permissions
-
-To obtain a SLAS token, follow the steps in the Shopper Login overview.
-
-#### AmOAuth2
-
-Custom scopes for AmOAuth2 can be assigned to a client in Account Manager. For example:
-
-> Account Manager OAuth2 scopes configuration for Custom APIs
-
-To obtain an Account Manager token follow the steps in the Authorization for Admin APIs guide.
-
-Unauthorized requests receive a 401 Unauthorized response.
-
-### 3.4 Complete Security Scheme Definition
-
-While endpoint registration does not require the complete definition of the security schemes, it can be useful to have a complete and valid scheme to enable the creation of documentation, tests and code stubs, and mock requests. The following code provides a complete example:
-
-```yaml
-components:
-  securitySchemes:
-    ShopperToken:
-      type: oauth2
-      flows:
-        authorizationCode:
-          authorizationUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
-          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
-          scopes:
-            c_my-scopes: description of my-scopes
-        clientCredentials:
-          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
-          scopes:
-            c_my-scopes: description of my-scopes
-    AmOAuth2:
-      type: oauth2
-      flows:
-        authorizationCode:
-          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
-          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
-          scopes:
-            c_my-scopes: description of my-scopes
-        clientCredentials:
-          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
-          scopes:
-            c_my-scopes: description of my-scopes
-```
-
-## 4. Core Concept: The Three Pillars of a Custom API
-
-Every Custom SCAPI Endpoint is built from three mandatory files, located within a dedicated cartridge directory: `your_cartridge/cartridge/rest-apis/{api-name}/`.
-
-- **`schema.yaml` (The Contract)**: An OpenAPI 3.0 specification that defines the endpoint's URL path, HTTP method, parameters, security requirements, and response models. SCAPI uses this for automated request validation.
-
-- **`script.js` (The Logic)**: A server-side B2C Commerce script (`dw.*` packages) that contains the business logic. It must export a public function with a name that exactly matches the `operationId` in the schema.
-
-- **`api.json` (The Mapping)**: A simple JSON file that links the `operationId` from the schema to the correct implementation script.
-
-## 5. Quick Start Example: A "Loyalty Info" Endpoint
-
-Here is a complete example for a custom Shopper API endpoint `GET /custom/loyalty-api/v1/.../loyalty-info?c_customer_id={id}`.
-
-### Directory Structure
-
-```
-int_loyalty_api/
-└── cartridge/
-    └── rest-apis/
-        └── loyalty-api/
-            ├── schema.yaml
-            ├── loyalty.js
-            └── api.json
-```
-
-### `schema.yaml`
-
-```yaml
-openapi: 3.0.0
-info:
-  title: Loyalty Information API
-  version: "1.0.0" # Becomes /v1/ in the URL
-paths:
-  /loyalty-info:
-    get:
-      summary: Retrieves loyalty points for a customer.
-      operationId: getLoyaltyInfo # Must match the exported function name
-      parameters:
-        - name: siteId # Required for Shopper APIs
-          in: query
-          required: true
-          schema:
-            type: string
-            minLength: 1
-        - name: c_customer_id # Custom parameters must be prefixed with 'c_'
-          in: query
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Successful retrieval of loyalty information.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/LoyaltyInfo'
-        '404':
-          description: Customer not found.
-      security:
-        - ShopperToken: [c_read_loyalty] # Apply security scheme and custom scope
-components:
-  schemas:
-    LoyaltyInfo:
-      type: object
-      properties:
-        tier:
-          type: string
-        points:
-          type: integer
-  securitySchemes:
-    ShopperToken: # Define the security scheme for Shopper APIs
-      type: oauth2
-      flows:
-        clientCredentials:
-          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/my-org-id/oauth2/token
-          scopes:
-            c_read_loyalty: "Read access to loyalty data." # Define custom scope
-```
-
-### `loyalty.js`
-
-```javascript
-'use strict';
-
-var RESTResponseMgr = require('dw/system/RESTResponseMgr');
-var CustomerMgr = require('dw/customer/CustomerMgr');
-
-/**
- * Implements the getLoyaltyInfo operationId.
- */
-exports.getLoyaltyInfo = function () {
-    var customerId = request.getHttpParameterMap().get('c_customer_id').getStringValue();
-    var customer = CustomerMgr.getCustomerByCustomerNumber(customerId);
-
-    // IMPORTANT: Add fine-grained authorization check here.
-    // e.g., verify request.user.profile.customerNo === customerId
-
-    if (customer) {
-        var loyaltyData = {
-            tier: 'Gold',
-            points: 25800
-        };
-        RESTResponseMgr.createSuccess(loyaltyData).render();
-    } else {
-        RESTResponseMgr.createError(404, "customer-not-found", "Customer Not Found", "Customer ID is unknown.").render();
-    }
-};
-
-// Function must be public to be exposed as an endpoint
-exports.getLoyaltyInfo.public = true;
-```
-
-### `api.json`
-
-```json
-{
-  "endpoints": [
-    {
-      "endpoint": "getLoyaltyInfo",
-      "schema": "schema.yaml",
-      "implementation": "loyalty"
-    }
-  ]
-}
-```
-
-## 5.1 Working with Path Parameters
-
-When your OpenAPI schema defines parameters with `in: path`, you must use the `getSCAPIPathParameters()` method to access them in your script implementation.
-
-### Path Parameter Example
-
-**schema.yaml with path parameter:**
-```yaml
-openapi: 3.0.0
-info:
-  title: Product Reviews API
-  version: "1.0.0"
-paths:
-  /products/{productId}/reviews:
-    get:
-      summary: Get reviews for a specific product
-      operationId: getProductReviews
-      parameters:
-        - name: productId
-          in: path  # This is a path parameter
-          required: true
-          schema:
-            type: string
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Product reviews retrieved successfully
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Review'
-components:
-  schemas:
-    Review:
-      type: object
-      properties:
-        id:
-          type: string
-        rating:
-          type: integer
-        comment:
-          type: string
-```
-
-**script.js accessing path parameter:**
-```javascript
-'use strict';
-
-var RESTResponseMgr = require('dw/system/RESTResponseMgr');
-var ProductMgr = require('dw/catalog/ProductMgr');
-
-/**
- * Implements the getProductReviews operationId.
- */
-exports.getProductReviews = function () {
-    // Access path parameters using getSCAPIPathParameters()
-    var productId = request.getSCAPIPathParameters().get('productId');
-    
-    // Access query parameters using getHttpParameterMap()
-    var siteId = request.getHttpParameterMap().get('siteId').getStringValue();
-    
-    // Validate required path parameter
-    if (!productId) {
-        RESTResponseMgr.createError(400, "missing-product-id", 
-            "Missing Product ID", "Product ID is required in the path").render();
-        return;
-    }
-    
-    var product = ProductMgr.getProduct(productId);
-    if (!product) {
-        RESTResponseMgr.createError(404, "product-not-found", 
-            "Product Not Found", "Product with ID " + productId + " was not found").render();
-        return;
-    }
-    
-    // Business logic to fetch reviews
-    var reviews = [
-        {
-            id: "review-1",
-            rating: 5,
-            comment: "Excellent product!"
-        },
-        {
-            id: "review-2", 
-            rating: 4,
-            comment: "Good quality, fast shipping"
-        }
-    ];
-    
-    RESTResponseMgr.createSuccess(reviews).render();
-};
-
-exports.getProductReviews.public = true;
-```
-
-### Key Points for Path Parameters
-
-1. **Path Parameter Access**: Always use `request.getSCAPIPathParameters().get('parameterName')` for parameters defined with `in: path` in your OpenAPI schema.
-
-2. **Query Parameter Access**: Continue using `request.getHttpParameterMap().get('parameterName')` for parameters defined with `in: query`.
-
-3. **Parameter Validation**: Path parameters are automatically validated by SCAPI based on your schema, but you should still add business logic validation in your script.
-
-4. **URL Structure**: Path parameters become part of the URL structure. For example, `/products/{productId}/reviews` with `productId: "ABC123"` becomes `/products/ABC123/reviews`.
-
-5. **Multiple Path Parameters**: You can have multiple path parameters in a single endpoint:
-   ```yaml
-   paths:
-     /customers/{customerId}/orders/{orderId}:
-       get:
-         parameters:
-           - name: customerId
-             in: path
-             required: true
-           - name: orderId
-             in: path
-             required: true
-   ```
-
-   Access them individually:
-   ```javascript
-   var customerId = request.getSCAPIPathParameters().get('customerId');
-   var orderId = request.getSCAPIPathParameters().get('orderId');
-   ```
-
-
-## 5.2 Caching Strategies for Custom Endpoints
-
-### Platform Web-Tier Behavior
-
-- Commerce Cloud's application layer performs web-tier caching for **GET** requests across SCAPI API families. Custom endpoints participate automatically once a request reaches the platform.
-- Client-side caches (browser storage, SPA state, CDN/edge caches) continue to operate independently. Model your architecture with layered caches in mind so one layer's miss does not surprise you at runtime.
-
-### Personalized Cache Variants
-
-When personalization is enabled, the cache key is expanded with:
-
-- The complete set of active promotions
-- Active product sorting rules
-- Applicable price books
-- All active AB test groups
-
-That means two shoppers requesting the same URL can receive different cache entries if they fall into different promotional contexts (for example, promotion X vs. promotion Y). This is valuable for targeted experiences but increases cache cardinality. Use personalization only for well-sized shopper cohorts and monitor cache pressure.
-
-`response.setVaryBy('price_promotion')` is the only supported personalization flag. Product detail responses that expand prices or promotions—and product search responses with the `prices` expand—are already personalized by default.
-
-### Programmatic Cache Controls
-
-- `response.setExpires(Date.now() + ttlInMs)`: Sets the cache expiration timestamp. The TTL must be at least **1 second (1,000 ms)** and no more than **86,400 seconds (86,400,000 ms)**.
-- `response.setVaryBy('price_promotion')`: Opts into price/promotion-aware personalization for the response variant.
-
-```javascript
-// Example snippet within your endpoint script
-exports.getLoyaltyInfo = function (params) {
-  var loyaltyData = { id: params.c_customer_id, points: 1234 };
-
-  // Cache for five minutes and personalize by price/promotion eligibility when needed
-  response.setExpires(Date.now() + 5 * 60 * 1000);
-  // response.setVaryBy('price_promotion');
-
-  RESTResponseMgr.createSuccess(loyaltyData).render();
-};
-exports.getLoyaltyInfo.public = true;
-```
-
-### Cache-Key Design Tips
-
-- Introduce explicit query parameters (for example, `c_view=light`) when you need multiple cacheable variants from the same controller logic.
-- Avoid combining expansions with drastically different TTLs. The response inherits the **shortest** TTL from the set of requested expands, so pairing a 24-hour asset expand with a 60-second availability expand collapses the lifespan to 60 seconds.
-- Pair web-tier caching with application-tier caching (`CacheMgr.getCache().get(key, loader)`) to shield downstream services. See the Performance Best Practices guide for the full two-tier pattern.
-
-## 6. Core Best Practices
-
-### Design & Architecture
-
-**Shopper vs. Admin APIs**: Choose the correct type for your use case. This choice is critical and dictates security, required parameters, and performance limits.
-
-- **Shopper API**: For customer-facing applications. Requires `siteId` parameter. Secured by ShopperToken (SLAS). 10-second timeout.
-- **Admin API**: For merchant tools. Must not have `siteId`. Secured by AmOAuth2 (Account Manager). 60-second timeout.
-
-**BFF Pattern**: Create endpoints that aggregate data for specific UI components to reduce the number of client-side calls and improve performance.
-
-### Security
-
-- **Custom Scopes**: Every endpoint must be secured by exactly one custom scope defined in the `schema.yaml`. Scope names must start with `c_` (e.g., `c_read_loyalty`).
-- **Client Permissions**: The API client in SLAS (for Shopper) or Account Manager (for Admin) must be granted permission to use your custom scope.
-- **In-Script Authorization**: The platform validates the token and scope. You must validate that the authenticated user has permission to access the specific data they are requesting. This prevents privilege escalation attacks.
-
-### Performance
-
-- **Timeouts**: Respect the hard timeouts: 10 seconds for Shopper APIs and 60 seconds for Admin APIs.
-- **Efficient Scripting**: Avoid expensive API calls (e.g., `ProductMgr.getProduct()`) inside loops. Fetch data in bulk where possible.
-- **External Calls**: Use the Service Framework (`dw.svc.*`) for any third-party callouts. Set aggressive timeouts and enable the circuit breaker to prevent cascading failures.
-- **Caching**: Use Custom Caches (`dw.system.CacheMgr`) for data that is expensive to compute but doesn't change often.
-
-### Versioning
-
-- The URL version (e.g., `/v1/`) is automatically derived from the major version number in your `schema.yaml`'s `info.version` field (e.g., "1.0.0" or "1.2.5" both map to v1).
-- Introduce breaking changes (e.g., removing a field, changing a data type) in a new major version (e.g., 2.0.0 -> `/v2/`) to avoid disrupting existing clients.
-
-### Troubleshooting
-
-- **404 Not Found**: This almost always means the API failed to register. Systematically check your cartridge structure, file names, `operationId` matching, and `api.json` syntax.
-- **403 Forbidden**: The client's token is valid but is missing the required custom scope. Check the scope assignments in SLAS or Account Manager.
-- **504 Gateway Timeout**: Your script exceeded the performance limit. Use the Code Profiler to find and optimize the bottleneck in your code.
-
-
-## 7. Custom APIs vs. Hooks
-
-This is a critical architectural decision.
-
-- **Use Hooks to...** modify or augment the behavior of an existing, out-of-the-box SCAPI endpoint. For example, adding a custom attribute to the standard `/baskets` response.
-
-- **Use Custom APIs to...** create entirely new functionality that has no OOTB equivalent. For example, a store locator, a loyalty points service, or a newsletter signup endpoint.
-
-> **Note**: Choosing the wrong tool leads to technical debt. Do not use hooks to create net-new functionality.
-
----