### RAML AsMapRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates the AsMapRule, which enforces that properties starting and ending with '/' must be annotated with '(asMap)'. This example shows a LocalizedString type with this rule applied.

```RAML
types:
  LocalizedString:
    type: object
    (asMap):
        key: string
        value: string
    properties:
      /^[a-z]{2}$/: string
```

--------------------------------

### Install Dependencies Locally

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/generate-a-postman-collection.md

Command to install project dependencies using Yarn. This is a prerequisite for running local generation scripts if dependencies are missing or outdated.

```bash
yarn install
```

--------------------------------

### Example Payload for SetCustomField Action

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Provides a JSON example of the payload required for the 'setCustomField' update action, demonstrating the structure for specifying the field name and its value.

```JSON
{
  "action": "setCustomField",
  "name": "ExampleStringTypeField",
  "value": "TextString"
}
```

--------------------------------

### RAML DiscriminatorNameRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Explains the DiscriminatorNameRule, ensuring that when a Discriminator Value is set, it is correctly specified. This example shows how to set the discriminator and its value.

```RAML
types:
  FooUpdateAction:
    type: object
    discriminator: type
    properties:
      type: string
  BarFoo:
    type: FooUpdateAction
    discriminatorValue: bar
```

--------------------------------

### Annotation Usage Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates how annotations, defined in 'annotations.raml', are applied within RAML files to add metadata, such as marking a field as beta.

```raml
  lastModifiedBy?: 
    type: LastModifiedBy
    (beta): true
```

--------------------------------

### API Field Definition Examples

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates how to define new fields within Commercetools API resources, covering data types, constraints, optionality, and metadata like beta status or deprecation. Examples include number, string, array, and object properties.

```APIDOC
accessTokenValiditySeconds?: 
  type: number
  format: int32
  minimum: 3600
  maximum: 604800
  default: 172800

```

```APIDOC
key?: 
  type: string
  pattern: ^[A-Za-z0-9_-]+$
  minLength: 2
  maxLength: 256

```

```APIDOC
geoLocation?: 
  type: GeoJson
  description: |
    GeoJSON geometry object encoding the geo location.

```

--------------------------------

### Example Payload for SetCustomType Action

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Shows a JSON example for the 'setCustomType' update action, illustrating how to reference a custom type by ID and provide a container for custom field values.

```JSON
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringTypeField": "TextString"
  }
}
```

--------------------------------

### Create API Method with URI Parameter and GET Operation

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Details the process of creating a new API method for an endpoint, typically involving a URI parameter and an HTTP method like GET. This involves modifying related files, declaring the method in an annotation, defining the baseResource with URI parameter and resource type, and specifying the HTTP method response.

```APIDOC
/password-token={passwordToken}:
  (methodName): withPasswordToken
  type:
    baseResource:
      uriParameterName: passwordToken
      resourceType: Customer
  get:
    displayName: Get customer by password verification token
    securedBy: [oauth_2_0: { scopes: ['view_customers:{projectKey}'] }]
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/customer.example.json
```

--------------------------------

### Commercetools API: Create Create Endpoint

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Defines a POST endpoint for creating new resources in the commercetools API. It includes resource details, security requirements, request body examples, and success responses.

```APIDOC
type:
  baseDomain:
    resourceType: Order
    resourceQueryType: OrderPagedQueryResponse
    resourceDraft: OrderFromCartDraft
    whereExample: 'customerEmail = "john.doe@example.com"'
    sortExample: createdAt asc
(updateable): Order
(deleteable): Order
(createable): OrderFromCartDraft
description:
  An order can be created from a order, usually after a checkout process has
  been completed.
post:
  securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
  is:
    - conflicting
  description: |
    Creates an order from a Cart.
    The cart must have a shipping address set before creating an order.
    When using the Platform TaxMode, the shipping address is used for tax calculation.
  body:
    application/json:
      example: !include ../examples/order-create.example.json
  responses:
    201:
      body:
        application/json:
          example: !include ../examples/order.example.json
```

--------------------------------

### RAML FilenameRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates the FilenameRule, which checks if new files are included in types.raml and if the displayName differs from the filename. It requires the name to include the domain/package.

```RAML
Foo: !include foo/FooBar.raml
```

--------------------------------

### RAML NestedTypeRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Details the NestedTypeRule, which forbids nested types and properties. It accepts only properties and their defined types once, showing valid examples of object and array properties.

```RAML
types:
  FooObject:
    type: object
    properties:
      meta:
        type: object
        description: valid
  Bar:
    type: object
    properties:
      valid: string
      validBaz: Baz
  FooArray:
    type: object
    properties:
      validArr:
        type: string[]
```

--------------------------------

### RAML NamedBodyTypeRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Explains the NamedBodyTypeRule, which ensures that the body type is defined for either success responses or request bodies within methods. It shows an example of defining request and response bodies.

```RAML
get:
  body:
    application/json:
      example: !include ../examples/cart-create.example.json
  responses:
    201:
      body:
        application/json:
          example: !include ../examples/cart.example.json
```

--------------------------------

### PolymorphicSubtypesRule RAML Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates the PolymorphicSubtypesRule in RAML, ensuring a type defines a discriminator if it has subtypes for correct deserialization. It defines base types and their subtypes.

```raml
types:
  Foo:
    type: object
    discriminator: type
    properties:
      type: string
  SubFoo:
    discriminatorValue: sub
    type: Foo
  InvalidBar:
    type: object
    description: InvalidBar
    properties:
      name: string
  SubBar:
    description: SubBar
    type: InvalidBar
  SubBar2:
    type: InvalidBar
```

--------------------------------

### RAML BooleanPropertyNameRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates the BooleanPropertyNameRule, which prevents property names from starting with 'is' if their type is Boolean. It shows both invalid and valid property naming conventions.

```RAML
  Invalid:
    type: object
    properties:
      isBad: boolean
  Valid:
    type: object
    properties:
      /a-z/: boolean
      good: boolean
      isolated: boolean
      isFine: string
```

--------------------------------

### Example Custom Field Structure in Resource

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates how custom fields are represented within a resource object's 'custom' property in JSON, including the type reference and the fields themselves.

```JSON
{
  "custom": {
    "type": {
      "typeId": "type",
      "id": "3ae9bcca-df23-443e-bd22-0c592f9694fa"
    },
    "fields": {
      "offer_name": "SuperMax"
    }
  }
}
```

--------------------------------

### Commercetools API: Create Query Endpoint

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Defines a GET endpoint for querying resources in the commercetools API. It specifies resource types, query parameters, security scopes, and response structures.

```APIDOC
type:
  baseDomain:
    resourceType: Cart
    resourceQueryType: CartPagedQueryResponse
    resourceDraft: CartDraft
    whereExample: 'customerEmail = "john.doe@example.com"'
    sortExample: createdAt asc
(updateable): Cart
(deleteable): Cart
(createable): CartDraft
description: A shopping cart holds product variants and can be ordered.
get:
  securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
  queryParameters:
    customerId?:
      type: string
  responses:
    200:
      body:
        application/json:
          example: !include ../examples/carts.example.json
```

--------------------------------

### QueryParameterPlaceholderAnnotationRule: Define placeholder query parameters

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates how to define query parameters with a '(placeholderParam)' annotation when the parameter name starts and ends with '/'. It requires 'paramName', 'template', and 'placeholder' fields.

```APIDOC
queryParameters:
  "/text.[a-z]{2}(-[A-Z]{2})?/":
    (placeholderParam):
      paramName: text
      template: text.<locale>
      placeholder: locale
```

--------------------------------

### RAML CamelCaseRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Shows the CamelCaseRule, which validates that property names adhere to camelCase conventions, excluding 'error_description'. Hyphens are not permitted in property names.

```RAML
    properties:
      /a-z/: string
      camelCase: string
```

--------------------------------

### RAML NamedStringEnumRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates the NamedStringEnumRule, which requires string types without a pattern to have defined Enum values. It shows a valid enum definition and a string with a pattern.

```RAML
types:
  Foo:
    type: string
    description: foo
    enum:
      - bar
  Bar:
    type: string
    pattern: /a-z/
```

--------------------------------

### RAML DatetimeRule Examples

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Details the DatetimeRule for properties of type DateTime, TimeOnly, or DateOnly. It requires names to end with 'At', 'From', 'To', or 'Until', and for date ranges, specific 'From' and 'To'/'Until' properties are mandatory.

```RAML
  FooAtDateTime:
    type: object
    properties:
      fooAt: datetime
  FooRangeDateTime:
    type: object
    properties:
      fooFrom: datetime
      fooTo: datetime
  ValidDateRange:
    type: object
    properties:
      validFrom: date-only
      validUntil: date-only
```

--------------------------------

### RAML DiscriminatorParentRule Example

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates the DiscriminatorParentRule, which mandates that the discriminator type must be set at the attribute level, not as a parent type. It shows correct and incorrect ways to define discriminators.

```RAML
types:
  Foo:
    type: object
    discriminator: type
    properties:
      type: string
  Baz:
    type: object
    properties:
      type: string
  FooBar:
    discriminator: type
    properties:
      type: string
  FooBaz:
    discriminator: type
    type: Foos
    properties:
      type: string
  Foos:
    properties:
      id: string
```

--------------------------------

### Define Commercetools Message Data Types

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Examples of RAML definitions for message types and their payloads. These snippets illustrate how to define custom message structures, including specifying the parent type, display name, discriminator value, and properties.

```RAML
#%RAML 1.0 DataType
(package): Message
type: Message
displayName: CategoryCreatedMessage
discriminatorValue: CategoryCreated
properties:
  category:
    type: Category

```

```RAML
#%RAML 1.0 DataType
(package): Message
type: MessagePayload
displayName: CategoryCreatedMessagePayload
discriminatorValue: CategoryCreated
properties:
  category:
    type: Category

```

--------------------------------

### Run RAML Validator Locally

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Provides instructions on how to run the RAML validator tool locally to check new code against RAML files. It specifies the command to execute for validation.

```Shell
yarn raml:validate
```

--------------------------------

### Commercetools Security Schemes Configuration

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates the configuration of security schemes in Commercetools API, specifically focusing on authorization and access token URIs, and the definition of OAuth scopes. This block shows common settings for authentication.

```raml
settings:
  authorizationUri: https://auth.europe-west1.gcp.commercetools.com/oauth/token
  accessTokenUri: https://auth.europe-west1.gcp.commercetools.com/oauth/token
  authorizationGrants: [client_credentials]
  scopes:
    - 'manage_project:{projectKey}'
    - 'manage_products:{projectKey}'
    - 'view_products:{projectKey}'
```

--------------------------------

### Run Postman Collection Generation Workflow (GitHub Action)

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/generate-a-postman-collection.md

Instructions for triggering the 'Generate postman collection' GitHub Action. This workflow automates the creation of a Postman Collection artifact from a specified branch in the commercetools-docs repository.

```yaml
# Example of how to trigger the GitHub Action via the UI
# Navigate to the Actions tab in the commercetools-docs repository
# Select 'Generate postman collection' workflow
# Click 'Run workflow'
# Choose the desired branch from the dropdown
# Click 'Run workflow' again
# The output artifact will be 'commercetools-postman-collection.zip'
```

--------------------------------

### ResourceCatchAllRule: Avoid ambiguous catch-all paths

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Ensures that only one catch-all path (e.g., '/{id}/options') exists for a resource collection to prevent ambiguity. It recommends using distinct path segments for clarity.

```APIDOC
/{projectKey}:
  /categories:
    /key={key}:
    /{id}:
```

--------------------------------

### Resource Type ID Enumeration and Descriptions

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates the YAML structure for defining resource type IDs in an enumeration and providing descriptive text for each, used for API type identification.

```YAML
enum:
  - <resourceTypeID_1>
  - <resourceTypeID_2>
(enumDescriptions):
  <resourceTypeID_1>: |
    [<Resource>](ctp:api:type:<Resource>)
  <resourceTypeID_2>: |
    [<Object>](ctp:api:type:Object) on [<Resource>](ctp:api:type:<Resource>)
```

--------------------------------

### RAML Trait Definition and Usage

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Explains the process of creating and using RAML traits for code reusability. It shows how to define a trait in a separate file and then include and apply it within resource definitions, such as for query parameters.

```raml
traits:
  priceSelecting: !include traits/price-selecting.raml

# In a resource file (e.g., product-projections-search.raml):
get:
  is:
    - priceSelecting
```

--------------------------------

### PackageDefinedRule: Define (package) annotation

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Ensures the '(package)' annotation is defined when creating a new Library. This is crucial for organizing and identifying library components within the API definition.

```APIDOC
types:
  BaseResource:
    type: object
    properties:
      id:
        (identifier): true
        type: string
        description: The unique ID of the cart.

(package): Cart
displayName: Cart
(updateType): CartUpdate
type: BaseResource
```

--------------------------------

### Message and Payload Definition Convention

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Describes the convention for defining message types and their corresponding payloads. Creating a Message file automatically generates its Payload in the '/message/payload' folder, following specific naming patterns.

```raml
(package): Message
displayName: OrderCreatedMessage
type: Message
properties:
  type:
    type: string
    enum: ["OrderCreated"]
  payload:
    type: OrderCreatedMessagePayload
```

```raml
(package): Message
displayName: OrderCreatedMessagePayload
type: object
properties:
  orderId:
    type: string
  orderNumber:
    type: string
  orderState:
    type: OrderState
  customer:
    type: CustomerReference
  store:
    type: StoreReference
  lineItems:
    type: array
    items: LineItem
  customLineItems:
    type: array
    items: CustomLineItem
  totalPrice:
    type: Money
  taxedPrice:
    type: TaxedPrice
  shippingInfo:
    type: ShippingInfo
  billingAddress:
    type: Address
  shippingAddress:
    type: Address
  paymentInfo:
    type: PaymentInfo
  discountCodes:
    type: array
    items: DiscountCodeInfo
  taxMode:
    type: TaxMode
  taxRoundingMode:
    type: TaxRoundingMode
  inventoryMode:
    type: InventoryMode
  itemShippingDetails:
    type: ItemShippingDetails
  origin:
    type: Origin
  customerGroup:
    type: CustomerGroupReference
  country:
    type: string
  state:
    type: StateReference
  shippingState:
    type: ShippingState
  syncInfo:
    type: array
    items: SyncInfo
  refusedGifts:
    type: array
    items: GiftLineItem
  custom:
    type: CustomFields
```

--------------------------------

### Resource Data and Draft Definition

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Defines the structure for resource data and its corresponding draft, including properties and update types. Follows conventions for naming and organization within the API reference.

```raml
(package): CartDiscount
type: object
displayName: CartDiscount
properties:
  id:
    type: string
  version:
    type: number
    format: int64
  createdAt:
    type: string
    format: date-time
  lastModifiedAt:
    type: string
    format: date-time
  key:
    type: string
  name:
    type: LocalizedString
  description:
    type: LocalizedString
  discountCode:
    type: DiscountCodeInfo
  cartPredicate:
    type: CartPredicate
  target:
    type: DiscountTarget
  restrictions:
    type: CartDiscountRestrictions
  validFrom:
    type: string
    format: date-time
  validUntil:
    type: string
    format: date-time
  isActive:
    type: boolean
  requiresShipping:
    type: boolean
  shippingCost:
    type: DiscountedLineItemPrice
  taxCategory:
    type: TaxCategoryReference
  shippingRateInput:
    type: ShippingRateInput
  sortOrder:
    type: string
  customerGroup:
    type: CustomerGroupReference
  country:
    type: string
  buyerRatingSpecialStatus:
    type: BuyerRatingSpecialStatus
  exclusiveActive:
    type: boolean
  multiBuyLineItems:
    type: MultiBuyLineItems
  multiBuyCustomLineItems:
    type: MultiBuyCustomLineItems
  value:
    type: DiscountValue
  actions:
    type: array
    items: CartDiscountUpdateAction
```

```raml
(package): CartDiscount
type: object
displayName: CartDiscountDraft
properties:
  key:
    type: string
  name:
    type: LocalizedString
  description:
    type: LocalizedString
  discountCode:
    type: DiscountCodeInfo
  cartPredicate:
    type: CartPredicate
  target:
    type: DiscountTarget
  restrictions:
    type: CartDiscountRestrictions
  validFrom:
    type: string
    format: date-time
  validUntil:
    type: string
    format: date-time
  isActive:
    type: boolean
  requiresShipping:
    type: boolean
  shippingCost:
    type: DiscountedLineItemPrice
  taxCategory:
    type: TaxCategoryReference
  shippingRateInput:
    type: ShippingRateInput
  sortOrder:
    type: string
  customerGroup:
    type: CustomerGroupReference
  country:
    type: string
  buyerRatingSpecialStatus:
    type: BuyerRatingSpecialStatus
  exclusiveActive:
    type: boolean
  multiBuyLineItems:
    type: MultiBuyLineItems
  multiBuyCustomLineItems:
    type: MultiBuyCustomLineItems
  value:
    type: DiscountValue
```

--------------------------------

### Create Delete Endpoint with URI Parameters

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Defines how to create a delete endpoint in RAML by incorporating URI parameters, such as an ID or Key. It requires adding specific parts to the code, including the URI parameter, methodName, and the delete method, referencing existing sections for query and create endpoints.

```APIDOC
/key={key}:
  (methodName): withKey
  type:
    baseResource:
      uriParameterName: key
      resourceType: Cart
      resourceUpdateType: CartUpdate
  delete:
    is:
      - dataErasure
    securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/cart.example.json
```

--------------------------------

### Define Resource Endpoint in RAML

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Explains how to include resource definitions from separate RAML files into the main API definition. This promotes modularity by organizing endpoints into distinct files, such as 'stores.raml'.

```RAML
/stores: !include resources/stores.raml

```

--------------------------------

### API Type Definitions Structure

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Outlines the structure and files required for defining new API types in commercetools. This includes BaseResources, Draft objects, PagedQueryResponse, Reference, ResourceIdentifier, Update, and UpdateAction definitions, each extending common API types.

```APIDOC
1. BaseResources: Define resource structure, updateType, and properties (e.g., Category.raml).
2. Draft: Object for create method payload (e.g., CategoryDraft.raml).
3. PagedQueryResponse: Extends PagedQueryResponse.raml (e.g., CategoryPagedQueryResponse.raml).
4. Reference: Extends Reference.raml (e.g., CategoryReference.raml).
5. ResourceIdentifier: Extends ResourceIdentifier.raml (e.g., CategoryResourceIdentifier.raml).
6. Update: Defines updateType from BaseResources, extends Update.raml (e.g., CategoryUpdate.raml).
7. UpdateAction: Defines actions within Update, extends UpdateAction.raml (e.g., CategoryUpdateAction.raml).
```

--------------------------------

### Paged Query Response Convention

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates the naming convention for paged query responses, which append 'PagedQueryResponse' to the resource name. This ensures consistent structure for list endpoints.

```raml
(package): CartDiscount
type: CartDiscountPagedQueryResponse
displayName: CartDiscountPagedQueryResponse
properties:
  limit:
    type: number
  offset:
    type: number
  count:
    type: number
  total:
    type: number
  results:
    type: array
    items: CartDiscount
```

--------------------------------

### Generate Postman Collection Locally

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/generate-a-postman-collection.md

Command to generate a Postman Collection from the commercetools-docs repository locally. It requires Node.js and Yarn. The command executes a script to build the collection files.

```bash
yarn run generate-postman
```

--------------------------------

### Commercetools API RAML Annotations

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Documentation for various RAML annotations used in the commercetools API specifications. These annotations define metadata, behavior, and relationships for API elements.

```APIDOC
Annotation Usage in RAML:

General Format:
  (annotationName): value

Specific Examples:

(placeholderParam):
  Used for query parameters with REGEX, defining parameter name, template, and placeholder.
  Example:
    queryParameters:
      /text\.[a-z]{2}(-[A-Z]{2})?/: 
        (placeholderParam):
          paramName: text
          template: text.<locale>
          placeholder: locale

(markDeprecated): true
  Indicates that an endpoint, property, or class is deprecated.

(identifier):
  Specifies the main key as an identifier for a property.
  Example:
    id:
      (identifier): true
      type: string

(elementIdentifier):
  Used with (identifier) when the key is not identical to the 'id'.
  Example:
    name:
      (identifier): true
      (elementIdentifier): true
      type: string
      description: ''

(updateType):
  Specifies the related <Resource>Update type for a resource definition.
  Must be mentioned in the resource definition itself.

(updateable):
  Assigns resource data and must be defined in resource files.
  Example:
    (updateable): Cart

(deleteable):
  Assigns resource data and must be defined in resource files.
  Example:
    (deleteable): Cart

(createable):
  Assigns resource data draft and must be defined in resource files.
  Example:
    (createable): CartDraft

(methodName):
  Declares the method name used in SDKs for a specific request.

(asMap):
  Used for key => value mapping, especially for properties in REGEX format.
  Example:
    (asMap):
      key: string
      value: string
    properties:
      /^[a-z]{2}(-[A-Z]{2})?$/:
        type: string

(deprecated):
  Indicates deprecation of an endpoint, property, or class.

Namespaced Annotations (e.g., Connect API):
  When using APIs with defined namespaces, prefix annotations with the namespace.
  Example:
    uses:
      annotations: annotationTypes/annotations.raml
      postman: annotationTypes/postman.raml

    (annotations.placeholderParam):
    (annotations.markDeprecated): true

```

--------------------------------

### SdkBaseUriRule: Declare (sdkBaseUri) annotation

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Checks for the declaration of the '(sdkBaseUri)' annotation at the API settings level. This annotation is used to specify the base URI for SDKs.

```APIDOC
annotationTypes:
  sdkBaseUri: string

baseUri: https://api.{region}.commercetools.com
(sdkBaseUri): https://api.europe-west1.commercetools.com
baseUriParameters: {}
```

--------------------------------

### ResourcePluralRule: Use plural for resource names

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Applies plural naming conventions to resource names, excluding specific exceptions like 'inventory', 'login', 'me', 'import', and 'in-store'. This aligns with common English grammar for collections.

```APIDOC
/{projectKey}:
  /categories:
  /inventory:
  /login:
  /me:
  /in-store:
```

--------------------------------

### RAML Deprecation Annotation Usage

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates the usage of the (markDeprecated) annotation in RAML files to mark endpoints, methods, or properties as deprecated. It shows how to apply the annotation with a boolean value and its placement within the API definition.

```raml
(markDeprecated): true   // this annotation on top is to deprecate the whole endpoint
/attributes:
  (markDeprecated): true
  post:
    (markDeprecated): true
    body:
      application/json:
        type: missing-data.MissingAttributesSearchRequest
    responses:
      202:
        body:
          application/json:
            type: common.TaskToken
            example: !include ../examples/missing-data-token.json
  /status:
    (markDeprecated): true
    /{taskId}:
      (markDeprecated): true
      (methodName): withTaskId
      uriParameters:
        taskId:
        type: string
      get:
        (markDeprecated): true
        responses:
          200:
            body:
              application/json:
                type: missing-data.MissingDataTaskStatus
                example: !include ../examples/missing-data-response.json
```

--------------------------------

### ResourceLowerCaseHyphenRule: Enforce lowercase and hyphenated resource paths

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Verifies that resource paths are entirely in lowercase and use hyphens for separation, promoting a consistent URL structure.

```APIDOC
/{projectKey}:
  /valid:
    /key={key}:
    /{id}:
  /valid-resource:
    /{id}:
```

--------------------------------

### UriParameterDeclaredRule: Declare URI parameters

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Ensures that all URI parameters used within resource definitions are properly declared in the 'uriParameters' section. This prevents undefined path variables.

```APIDOC
resourceTypes:
  base:
    uriParameters:
      <<uriParameterName>>: { type: string }
    get: {}
```

--------------------------------

### Set Base URI in RAML

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Demonstrates how to define a base URI for an API in RAML, including specifying region-specific parameters with an enum list. This ensures API requests are directed to the correct regional endpoint.

```RAML
baseUri: https://api.{region}.commercetools.com  // This is the general baseUri
baseUriParameters:
  region:
    type: string
    enum:             // here below are listed all of the regions available
      - us-east-2.aws
      - europe-west1.gcp

```

--------------------------------

### Error Definition Convention

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Explains the convention for defining error types, where error-specific files are placed in the '/error' folder and named using the error name followed by 'Error.raml'.

```raml
(package): Common
displayName: ErrorResponse
type: object
properties:
  statusCode:
    type: integer
  message:
    type: string
  code:
    type: string
  errors:
    type: array
    items: ErrorObject
```

--------------------------------

### SuccessBodyRule: Define success response body

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Verifies that the body type for success responses (e.g., 200 OK, 201 Created) is defined at the HTTP method level. This ensures clarity on successful response payloads.

```APIDOC
/categories:
  get:
    responses:
      200:
        body:
          application/json:
            type: object
  post:
    responses:
      201:
        body:
          application/json:
            type: object
```

--------------------------------

### Commercetools API: Create Update Endpoint by ID

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Defines an update endpoint for modifying existing resources using their ID. It specifies URI parameters, method names, security, request body, and response structures for updates.

```APIDOC
/{ID}:
  (methodName): withId
  type:
    baseResource:
      uriParameterName: ID
      resourceType: Cart
      resourceUpdateType: CartUpdate
  post:
    securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
    body:
      application/json:
        example: !include ../examples/cart-update.example.json
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/cart.example.json
```

--------------------------------

### Resource Update and Update Action Structure

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Details the generic structure for resource updates, including a version number and an array of actions. It also shows the definition of a specific update action, like 'CartDiscountChangeNameAction'.

```raml
(package): CartDiscount
type: object
displayName: CartDiscountUpdate
properties:
  version:
    type: number
    format: int64
  actions:
    type: array
    items: CartDiscountUpdateAction
```

```raml
(package): CartDiscount
type: CartDiscountUpdateAction
displayName: CartDiscountChangeNameAction
discriminatorValue: changeName
example: !include ../../../examples/CartDiscount/CartDiscountChangeNameAction.json
properties:
  name:
    type: LocalizedString
    description: ''
```

--------------------------------

### Common Type: LocalizedString

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Defines the 'LocalizedString' type, a common data structure used for fields that support multiple languages. It uses a map where keys are language codes.

```raml
(package): Common
displayName: LocalizedString
type: object
(asMap):
  key: string
  value: string
properties:
  /^[a-z]{2}(-[A-Z]{2})?$/:
    type: string
```

--------------------------------

### StringPropertySingularRule: Use singular for non-array string properties

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Ensures that string properties which are not arrays are named in the singular form, adhering to English grammar for individual items.

```APIDOC
types:
  Foo:
    type: object
    properties:
      validItem: string
      "/a-z/": string
      maxApplications: number
      hasChanges: boolean
```

--------------------------------

### APIDOC: Number Types Convention

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/history/README.md

Defines conventions for documenting number types (floats and integers) in API specifications for proper parsing by RAML transformers. Floats are defined using the generic 'number' type, while integers require explicit 'type: integer' and 'format: int64' properties.

```APIDOC
Number Types Convention:

Floats:
  Properties are defined using the generic 'number' type.
  Example:
    properties:
      floatProperty?: number

Integers:
  Integers require explicit type and format definitions.
  Example:
    properties:
      integerProperty:
        description: integer description
        type: integer
        format: int64
```

--------------------------------

### QueryParameterCamelCaseRule: Validate query parameter naming

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Checks if query parameter names adhere to the lower camel case convention and consist only of alphanumeric characters and dots. It specifically excludes 'error_description'.

```APIDOC
queryParameters:
  customerId?: string
  "filter.query"?: string
```

--------------------------------

### Add Scope to Commercetools API

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Steps to add a new OAuth 2.0 scope to the commercetools API. This involves modifying resource files and security scheme definitions to include the new scope for authorization.

```RAML
get:
  securedBy:
    [
      oauth_2_0:
        {
          scopes:
            [
              'manage_project:{projectKey}',
              'view_products:{projectKey}',
              'view_categories:{projectKey}',
            ],
        },

```

```RAML
settings:
  authorizationUri: https://auth.europe-west1.gcp.commercetools.com/oauth/token
  accessTokenUri: https://auth.europe-west1.gcp.commercetools.com/oauth/token
  authorizationGrants: [client_credentials]
  scopes:
    - 'manage_project:{projectKey}'
    - 'manage_products:{projectKey}'
    - 'view_products:{projectKey}'
    - 'manage_orders:{projectKey}'

```

--------------------------------

### PostBodyRule: Validate POST method body

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Validates that the body is correctly set for POST methods. This rule complements the Named Body Type Rule by ensuring proper request body structure.

```APIDOC
/categories:
  get: {}
  post:
    body:
      application/json:
        type: object
```

--------------------------------

### PropertyPluralRule: Use plural for array properties

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Enforces the use of plural names for array property names, following English grammar rules. This improves consistency and readability of data structures.

```APIDOC
types:
  Foo:
    type: object
    properties:
      validItems: string[]
      money: string[]
```

--------------------------------

### Define Custom Field in Resource Definition

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Illustrates how to integrate the 'custom' field into a resource's RAML definition. This field is marked as optional ('?') and points to the 'CustomFields' type for read models.

```RAML
custom?: 
  type: CustomFields
  description: Custom Fields of this <object>.
```

--------------------------------

### APIDOC: Union Types Convention

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/history/README.md

Advises against the use of union types in API specifications as they may not be properly parsed or may cause errors with documentation tools. Definitions should eliminate union types wherever possible.

```APIDOC
Union Types Convention:

  Union types should generally be avoided.
  They may not be properly parsed or may generate errors.
  Definitions in this API eliminate union types wherever possible.
```

--------------------------------

### Define SetCustomField Update Action

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Specifies the RAML structure for a 'SetCustomField' update action. This includes defining the action's type, display name, discriminator value, and properties for the custom field's name and value.

```RAML
#%RAML 1.0 DataType
(package): <Resource>
type: <Resource>UpdateAction
displayName: <Resource>Set<embeddedObject>CustomFieldAction
discriminatorValue: <id for the update action>
example: !include ../../../examples/<Resource>/<Resource>Set<embeddedObject>CustomFieldAction.json
properties:
  name:
    type: string
  value?:
    type: CustomFieldValue
```

--------------------------------

### UnionTypePropertyRule: Disallow union types for properties

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Asserts that the usage of union types (e.g., 'string | number') is not allowed for property definitions. This rule promotes type safety and simplicity.

```APIDOC
types:
  Foo:
    type: object
    properties:
      validItems: string
      invalidItem: string | number
      invalidItemDesc:
        description: test
        type: string | number
      "/invalid[a-z]/": string | number
```

--------------------------------

### Define SetCustomType Update Action

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Details the RAML definition for a 'SetCustomType' update action. It outlines the action's type, display name, discriminator value, and properties for associating a custom type and its fields with a resource.

```RAML
#%RAML 1.0 DataType
(package): <Resource>
type: <Resource>UpdateAction
displayName: <Resource>Set<embeddedObject>CustomTypeAction
discriminatorValue: <id for the update action>
example: !include ../../../examples/<Resource>/<Resource>Set<embeddedObject>CustomTypeAction.json
properties:
  type?:
    type: TypeResourceIdentifier
  fields?:
    type: FieldContainer
```

--------------------------------

### UpdateActionNameRule: Validate UpdateAction type

Source: https://github.com/commercetools/commercetools-api-reference/blob/main/api-specs/readme.md

Verifies that a type referred to as an 'UpdateAction' is indeed valid if it's defined as a type inheriting from 'UpdateAction'.

```APIDOC
types:
  UpdateAction: { type: object }
  ValidAction:
    type: UpdateAction
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.