Updated API from documentation release

api-specs/api/examples/ProductSearch/product-search-request.example.json

@@ -0,0 +1,33 @@
+{
+  "query": {
+    "and": [
+      {
+        "fullText": {
+          "field": "name",
+          "language": "en",
+          "value": "banana"
+        }
+      },
+      {
+        "filter": [
+          {
+            "exact": {
+              "field": "variants.attributes.farming",
+              "fieldType": "text",
+              "value": "organic"
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "sort": [
+    {
+      "field": "name",
+      "language": "en",
+      "order": "desc"
+    }
+  ],
+  "limit": 10,
+  "offset": 0
+}

api-specs/api/examples/ProductSearch/product-search-response.example.json

@@ -0,0 +1,39 @@
+{
+  "total": 148,
+  "offset": 0,
+  "limit": 10,
+  "facets": [
+    {
+      "name": "countProducts",
+      "buckets": [
+        {
+          "key": "white",
+          "count": 37
+        }
+      ]
+    },
+    {
+      "name": "countVariants",
+      "buckets": [
+        {
+          "key": "white",
+          "count": 301
+        }
+      ]
+    }
+  ],
+  "results": [
+    {
+      "id": "8fde2af0-6a2f-4633-9ba4-83566f769a7f",
+      "matchingVariants": {
+        "allMatched": false,
+        "matchedVariants": [
+          {
+            "id": 1,
+            "sku": null
+          }
+        ]
+      }
+    }
+  ]
+}

api-specs/api/examples/Project/ProjectChangeProductSearchIndexingEnabledAction.json

@@ -1,4 +1,5 @@
 {
   "action": "changeProductSearchIndexingEnabled",
-  "enabled": true
+  "enabled": true,
+  "mode": "ProductsSearch"
 }

api-specs/api/resources/products.raml

@@ -11,7 +11,17 @@ type:
 description: |
   Products themselves are not sellable. Instead, they act as a parent structure for sellable Product Variants.
 get:
-  securedBy: [oauth_2_0: { scopes: ['view_products:{projectKey}'] }]
+  securedBy:
+    [
+      oauth_2_0:
+        {
+          scopes:
+            [
+              'view_products:{projectKey}',
+              'view_published_products:{projectKey}',
+            ],
+        },
+    ]
   is:
     - priceSelecting
   description: |-
@@ -212,3 +222,30 @@ post:
           body:
             application/json:
               example: !include ../examples/product-assigned-selections.example.json
+/search:
+  type: base
+  displayName: Product Search
+  description: |
+    This endpoint provides high-performance search queries over Products. Product Search allows searching through all products with a current projection in your Project.
+  post:
+    displayName: Search Products
+    securedBy: [oauth_2_0: { scopes: ['view_published_products:{projectKey}'] }]
+    body:
+      application/json:
+        type: ProductSearchRequest
+    responses:
+      200:
+        body:
+          application/json:
+            example: !include ../examples/ProductSearch/product-search-response.example.json
+            type: ProductPagedSearchResponse
+  head:
+    securedBy: [oauth_2_0: { scopes: ['project_settings:{projectKey}'] }]
+    description: |
+      Checks whether a search index for the Project's Products exists.
+      Returns a `200 OK` status if the index exists, a `404 Not Found` error otherwise.
+    responses:
+      200:
+        description: The search index exists and the Search Products endpoint is fully operational.
+      404:
+        description: The search index does not exist and the Search Products endpoint returns Error 404 only.

api-specs/api/ruleset.xml

@@ -54,6 +54,7 @@
                 <option type="exclude">lineItemOrder</option>
                 <option type="exclude">textLineItemOrder</option>
                 <option type="exclude">syncInfo</option>
+                <option type="exclude">localeProjection</option>
                 <option type="exclude">returnInfo</option>
                 <option type="exclude">value</option>
                 <option type="exclude">newState</option>
@@ -66,6 +67,7 @@
                 <option type="exclude">filter</option>
                 <option type="exclude">not</option>
                 <option type="exclude">or</option>
+                <option type="exclude">expand</option>
             </options>
         </rule>
         <rule>

api-specs/api/types/product-search/ProductPagedSearchResponse.raml

@@ -0,0 +1,33 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+displayName: ProductPagedSearchResponse
+type: object
+(beta): true
+properties:
+  total:
+    type: number
+    format: int64
+    minimum: 0
+    description: Total number of results matching the query.
+  offset:
+    type: number
+    format: int32
+    minimum: 0
+    maximum: 9900
+    description: |
+      Number of [elements skipped](/../api/general-concepts#offset).
+  limit:
+    type: number
+    format: int32
+    minimum: 0
+    maximum: 100
+    description: |
+      Number of [results requested](/../api/general-concepts#limit).
+  facets:
+    type: ProductSearchFacetResult[]
+    description: |
+      Results for [facets](/../api/projects/product-search#facets) when requested.
+  results:
+    type: ProductSearchResult[]
+    description: |
+      Search result containing the Products matching the search query.

api-specs/api/types/product-search/ProductSearchErrorResponse.raml

@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: ErrorResponse
+(beta): true
+displayName: ProductSearchErrorResponse
+properties:
+  statusCode:
+    description: The http status code of the response.
+    type: integer
+  message:
+    description: Describes the error.
+    type: string
+  errors?:
+    description: |
+      The errors that caused this error response.
+    type: ErrorObject[]

api-specs/api/types/product-search/ProductSearchMatchingVariantEntry.raml

@@ -0,0 +1,13 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+displayName: ProductSearchMatchingVariantEntry
+type: object
+(beta): true
+properties:
+  id:
+    type: number
+    format: int32
+    description: Unique identifier of the variant.
+  sku?:
+    type: string
+    description: SKU of the matching variant.

api-specs/api/types/product-search/ProductSearchMatchingVariants.raml

@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+displayName: ProductSearchMatchingVariants
+type: object
+(beta): true
+properties:
+  allMatched:
+    type: boolean
+    description: Whether the search criteria definitely matches for all Variants of the returned Product, like for Product-level fields. Is always `false` for search expressions on Variant-level fields.
+  matchedVariants:
+    type: ProductSearchMatchingVariantEntry[]
+    description: The variants matching the search criteria or empty if all matched.

api-specs/api/types/product-search/ProductSearchProjectionParams.raml

@@ -0,0 +1,43 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: object
+(beta): true
+displayName: ProductSearchProjectionParams
+properties:
+  expand?:
+    type: Expansion[]
+    description: |
+      Expands a `value` of type [Reference](ctp:api:type:Reference) in a [ProductProjection](ctp:api:type:ProductProjection).
+      In case the referenced object does not exist, the API returns the non-expanded reference.
+  staged?:
+    type: boolean
+    description: |
+      Set to `true` to retrieve the [staged](ctp:api:type:CurrentStaged) Product Projection
+  priceCurrency?:
+    type: CurrencyCode
+    description: |
+      The currency used for [Price selection](/projects/products#price-selection).
+  priceCountry?:
+    type: CountryCode
+    description: |
+      The country used for [Price selection](/projects/products#price-selection). Can only be used **in conjunction with** the `priceCurrency` parameter.
+  priceCustomerGroup?:
+    type: string
+    description: |
+      `id` of an existing [CustomerGroup](ctp:api:type:CustomerGroup) used for [Price selection](ctp:api:type:ProductPriceSelection). Can only be used **in conjunction with** the `priceCurrency` parameter.
+  priceChannel?:
+    type: string
+    description: |
+      `id` of an existing [Channel](ctp:api:type:Channel) used for [Price selection](ctp:api:type:ProductPriceSelection). Can only be used **in conjunction with** the `priceCurrency` parameter.
+  localeProjection?:
+    type: Locale[]
+    description: |
+      Used for [locale-based projection](ctp:api:type:ProductProjectionLocales).
+  storeProjection?:
+    type: string
+    description: |
+      `key` of an existing [Store](ctp:api:type:Store).
+      If the Store has defined some languages, countries, distribution or supply Channels,
+      they are used for projections based on [locale](ctp:api:type:ProductProjectionLocales), [price](ctp:api:type:ProductProjectionPrices)
+      and [inventory](ctp:api:type:ProductProjectionInventoryEntries).
+      If the Store has defined [Product Selections](ctp:api:type:ProductSelection), they have no effect on the results of this query.

api-specs/api/types/product-search/ProductSearchRequest.raml

@@ -0,0 +1,39 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: object
+(beta): true
+displayName: ProductSearchRequest
+example: !include ../../examples/ProductSearch/product-search-request.example.json
+properties:
+  query?:
+    type: SearchQuery
+    description: The search query against [searchable Product fields](/../api/projects/product-search#searchable-product-fields).
+  sort?:
+    type: SearchSorting[]
+    description: Controls how results to your query are sorted. If not provided, the results are sorted by relevance in descending order.
+  limit?:
+    type: number
+    format: int32
+    default: 20
+    maximum: 100
+    description: The maximum number of search results to be returned.
+  offset?:
+    type: number
+    format: int32
+    default: 0
+    maximum: 9900
+    description: The number of search results to be skipped in the response for pagination.
+  markMatchingVariants?:
+    type: boolean
+    default: false
+    description: The search can return Products where not all Product Variants match the search criteria. If `true`, the response will include a field called `matchingVariants` that contains the `sku` of Product Variants that match the search query. If the query does not specify any variant-level criteria, `matchingVariants` will be null signifying that all Product Variants are a match.
+  productProjectionParameters?:
+    type: ProductSearchProjectionParams
+    description: |
+      Set this field to `{}` to get the [ProductProjection](ctp:api:type:ProductProjection) included in the [ProductSearchResult](ctp:api:type:ProductSearchResult).
+      Include query parameters for controlling [Reference Expansion](/../api/general-concepts#reference-expansion) or [projections](/../api/projects/productProjections#projection-dimensions) according to your needs.
+      If not set, the result does not include the Product Projection.
+  facets?:
+    type: ProductSearchFacetExpression[]
+    description: |
+      Set this field to request [facets](/../api/projects/product-search#facets).

api-specs/api/types/product-search/ProductSearchResult.raml

@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+displayName: ProductSearchResult
+type: object
+(beta): true
+properties:
+  id:
+    (identifier): true
+    type: string
+    description: Unique identifier of the Product.
+  productProjection?:
+    type: ProductProjection
+    description: Contains Product Projection data for Products matching the `projection` field in the Search Products request.
+  matchingVariants?:
+    type: ProductSearchMatchingVariants
+    description: Describes the variants that matched the search criteria.

api-specs/api/types/product-search/facets/ProductSearchFacetCountExpression.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: ProductSearchFacetExpression
+(beta): true
+displayName: ProductSearchFacetCountExpression
+properties:
+  count:
+    type: ProductSearchFacetCountValue
+    description: Definition of the count facet.

api-specs/api/types/product-search/facets/ProductSearchFacetCountLevelEnum.raml

@@ -0,0 +1,11 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+displayName: ProductSearchFacetCountLevelEnum
+type: string
+(beta): true
+enum:
+  - products
+  - variants
+(enumDescriptions):
+  products: The query should count Products.
+  variants: The query should count Product Variants.

api-specs/api/types/product-search/facets/ProductSearchFacetCountValue.raml

@@ -0,0 +1,19 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: object
+(beta): true
+displayName: ProductSearchFacetCountValue
+properties:
+  name:
+    type: string
+  scope?:
+    type: ProductSearchFacetScopeEnum
+    description: Whether the facet must consider only the Products resulting from the search (`query`) or all the Products (`all`).
+    default: query
+  filter?:
+    type: SearchQuery
+    description: Additional filtering expression to apply to the search result before calculating the facet.
+  level?:
+    type: ProductSearchFacetCountLevelEnum
+    default: products
+    description: Specify whether to count Products (`products`) or Product Variants (`variants`).

api-specs/api/types/product-search/facets/ProductSearchFacetDistinctBucketSortBy.raml

@@ -0,0 +1,11 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: string
+(beta): true
+displayName: ProductSearchFacetDistinctBucketSortBy
+enum:
+  - count
+  - key
+(enumDescriptions):
+  count: Sort buckets by the count value.
+  key: Sort buckets by the bucket key.

api-specs/api/types/product-search/facets/ProductSearchFacetDistinctBucketSortExpression.raml

@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(package): ProductSearch
+type: object
+(beta): true
+displayName: ProductSearchFacetDistinctBucketSortExpression
+properties:
+  by:
+    type: ProductSearchFacetDistinctBucketSortBy
+    description: Defines whether to sort by bucket count or key.
+  order:
+    type: SearchSortOrder
+    description: Defines the sorting order.