Updated API from documentation release

api-specs/api/examples/CustomerSearch/CustomerPagedSearchResponse.json

@@ -0,0 +1,19 @@
+{
+  "results": [
+    {
+      "id": "e41337a0-ea96-4ddc-a9a4-d267976f21e0",
+      "relevance": 0.9264881
+    },
+    {
+      "id": "05cd5998-015c-4232-8943-ff8a1880bcbc",
+      "relevance": 0.6989829
+    },
+    {
+      "id": "09c3c5a2-6569-49dd-b021-af5de4cf4b02",
+      "relevance": 0.6989829
+    }
+  ],
+  "limit": 100,
+  "offset": 0,
+  "total": 3
+}

api-specs/api/examples/CustomerSearch/CustomerSearchIndexingStatusResponse.json

@@ -0,0 +1,11 @@
+{
+  "status": "Indexing",
+  "states": {
+    "indexed": 43242,
+    "failed": 0,
+    "estimatedTotal": 100000
+  },
+  "startedAt": "2023-08-15T12:56:07.89Z",
+  "retryCount": 2,
+  "lastModifiedAt": "2023-08-15T12:56:07.89Z"
+}

api-specs/api/examples/CustomerSearch/CustomerSearchRequest.json

@@ -0,0 +1,8 @@
+{
+  "query": {
+    "fullText": {
+      "field": "all",
+      "value": "john"
+    }
+  }
+}

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

@@ -0,0 +1,4 @@
+{
+  "action": "changeCustomerSearchStatus",
+  "status": "Activated"
+}

api-specs/api/resources/customers.raml

@@ -230,3 +230,42 @@ post:
         body:
           application/json:
             example: !include ../examples/customer.example.json
+/search:
+  type: base
+  displayName: Customer Search
+  description: |
+    This endpoint provides high-performance search queries over Customers.
+  post:
+    displayName: Search Customers
+    securedBy: [oauth_2_0: { scopes: ['view_customers:{projectKey}'] }]
+    body:
+      application/json:
+        type: CustomerSearchRequest
+    responses:
+      200:
+        body:
+          application/json:
+            type: CustomerPagedSearchResponse
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_customers:{projectKey}'] }]
+    description: |
+      Checks whether a search index for the Project's Customers exists.
+      Returns a `200 OK` status if the index exists or `404 Not Found` otherwise.
+    responses:
+      200:
+        description: The search index exists and the Search Customers endpoint is fully operational.
+      404:
+        description: The search index does not exist and the Search Customers endpoint returns Error 404 only.
+/search/indexing-status:
+  type: base
+  displayName: Customer Search Status
+  description: |
+    This endpoint provides information on the status of a Customer search for a project
+  get:
+    displayName: Customer Search Status
+    securedBy: [oauth_2_0: { scopes: ['view_project_settings:{projectKey}'] }]
+    responses:
+      200:
+        body:
+          application/json:
+            type: CustomerSearchIndexingStatusResponse

api-specs/api/ruleset.xml

@@ -77,6 +77,7 @@
                 <option type="exclude">taxCalculationMode</option>
                 <option type="exclude">acks</option>
                 <option type="exclude">oldStatus</option>
+                <option type="exclude">indexingStatus</option>
             </options>
         </rule>
         <rule>

api-specs/api/types/customer-search/CustomerIndexingProgress.raml

@@ -0,0 +1,18 @@
+#%RAML 1.0 DataType
+(package): CustomerSearch
+type: object
+(beta): true
+displayName: CustomerIndexingProgress
+properties:
+  indexed:
+    type: number
+    format: int32
+    description: The number of Customers successfully indexed.
+  failed:
+    type: number
+    format: int32
+    description: The number of Customers that failed to be indexed.
+  estimatedTotal:
+    type: number
+    format: int32
+    description: The estimated total number of Customers to be indexed.

api-specs/api/types/customer-search/CustomerIndexingStatus.raml

@@ -0,0 +1,17 @@
+#%RAML 1.0 DataType
+(package): Project
+type: string
+(beta): true
+displayName: CustomerIndexingStatus
+description: |
+  The current indexing status of Customer Search.
+(enumDescriptions):
+  Scheduled: Indexing is scheduled.
+  Indexing: Indexing is in progress.
+  Ready: Indexing is complete and the [Search Customers](/../api/projects/customer-search#search-customers) endpoint returns up-to-date results.
+  Failed: Indexing failed due to an internal error.
+enum:
+  - Scheduled
+  - Indexing
+  - Ready
+  - Failed

api-specs/api/types/customer-search/CustomerPagedSearchResponse.raml

@@ -0,0 +1,30 @@
+#%RAML 1.0 DataType
+(package): CustomerSearch
+displayName: CustomerPagedSearchResponse
+example: !include ../../examples/CustomerSearch/CustomerPagedSearchResponse.json
+type: object
+(beta): true
+properties:
+  total:
+    type: number
+    format: int64
+    minimum: 0
+    description: Total number of results matching the query.
+  limit:
+    type: number
+    format: int32
+    minimum: 0
+    maximum: 100
+    description: |
+      Number of [results requested](/../api/general-concepts#limit).
+  offset:
+    type: number
+    format: int32
+    minimum: 0
+    maximum: 9900
+    description: |
+      Number of [elements skipped](/../api/general-concepts#offset).
+  results:
+    type: CustomerSearchResult[]
+    description: |
+      Search result containing the Customers matching the search query.

api-specs/api/types/customer-search/CustomerSearchIndexingStatusResponse.raml

@@ -0,0 +1,24 @@
+#%RAML 1.0 DataType
+(package): CustomerSearch
+displayName: CustomerSearchIndexingStatusResponse
+type: object
+(beta): true
+example: !include ../../examples/CustomerSearch/CustomerSearchIndexingStatusResponse.json
+properties:
+  status:
+    type: CustomerIndexingStatus
+    description: Current status of indexing the Customer Search.
+  states?:
+    type: CustomerIndexingProgress
+    description: Progress of indexing. Only available when indexing is in progress.
+  startedAt?:
+    type: datetime
+    description: Date and time (UTC) when the last indexing started.
+  lastModifiedAt?:
+    type: datetime
+    description: Time when the status was last modified.
+  retryCount?:
+    type: number
+    format: int32
+    description: |
+      Indicates how many times the system tried to start indexing after failed attempts. The counter is set to null after an indexing finished successfully.

api-specs/api/types/customer-search/CustomerSearchRequest.raml

@@ -0,0 +1,25 @@
+#%RAML 1.0 DataType
+(package): CustomerSearch
+type: object
+(beta): true
+example: !include ../../examples/CustomerSearch/CustomerSearchRequest.json
+displayName: CustomerSearchRequest
+properties:
+  query?:
+    type: SearchQuery
+    description: The Customer search query.
+  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.

api-specs/api/types/customer-search/CustomerSearchResult.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(package): CustomerSearch
+displayName: CustomerSearchResult
+type: object
+(beta): true
+properties:
+  id:
+    (identifier): true
+    type: string
+    description: |
+      `id` of the [Customer](ctp:api:type:Customer) matching the search query.
+  relevance:
+    type: number
+    description: |
+      How closely this customer matches the search query.

api-specs/api/types/error/CustomerSearchProjectNotIndexedError.raml

@@ -0,0 +1,17 @@
+#%RAML 1.0 DataType
+(package): Error
+type: ErrorObject
+displayName: CustomerSearchProjectNotIndexedError
+description: |
+  Returned as response to the [Search Customers](/projects/customer-search#search-customers) request in case the Customer Search API is not active for the Project.
+
+  Use the [Change Customer Search Status](ctp:api:type:ProjectChangeCustomerSearchStatusAction) update action on the [Project](/projects/project#update-project) to activate the API.
+properties:
+  code:
+    type: string
+    description: |
+      `"ResourceNotFound"`
+  message:
+    type: string
+    description: |
+      `"Project not yet indexed"`

api-specs/api/types/error/graphql/GraphQLCustomerSearchProjectNotIndexedError.raml

@@ -0,0 +1,13 @@
+#%RAML 1.0 DataType
+(package): Error
+type: GraphQLErrorObject
+displayName: GraphQLCustomerSearchProjectNotIndexedError
+description: |
+  Returned as response to the [Search Customers](/projects/customer-search#search-customers) request in case the Customer Search API is not active for the Project.
+
+  Use the [Change Customer Search Status](ctp:api:type:ProjectChangeCustomerSearchStatusAction) update action on the [Project](/projects/project#update-project) to activate the API.
+properties:
+  code:
+    type: string
+    description: |
+      `"ResourceNotFound"`

api-specs/api/types/project/CustomerSearchStatus.raml

@@ -0,0 +1,14 @@
+#%RAML 1.0 DataType
+(package): Project
+type: string
+(beta): true
+displayName: CustomerSearchStatus
+description: |
+  Specifies the status of the [Customer Search](/../api/projects/customer-search) index.
+  You can change the status using the [Change Customer Search Status](ctp:api:type:ProjectChangeCustomerSearchStatusAction) update action.
+(enumDescriptions):
+  Activated: indicates that the [Customer Search](/../api/projects/customer-search#search-customers) endpoint is fully operational.
+  Deactivated: indicates that the Customer Search enpoint is currently not active.
+enum:
+  - Activated
+  - Deactivated

api-specs/api/types/project/updates/ProjectChangeCustomerSearchStatusAction.raml

@@ -0,0 +1,11 @@
+#%RAML 1.0 DataType
+(package): Project
+type: ProjectUpdateAction
+(beta): true
+displayName: ProjectChangeCustomerSearchStatusAction
+discriminatorValue: changeCustomerSearchStatus
+example: !include ../../../examples/Project/ProjectChangeCustomerSearchStatusAction.json
+properties:
+  status:
+    type: CustomerSearchStatus
+    description: Activates or deactivates the [Customer Search](/../api/projects/customer-search) feature. Activation will trigger building a search index for the Customers in the Project.

api-specs/api/types/types.raml

@@ -403,6 +403,12 @@ CustomerGroupChangeNameAction: !include customer-group/updates/CustomerGroupChan
 CustomerGroupSetCustomFieldAction: !include customer-group/updates/CustomerGroupSetCustomFieldAction.raml
 CustomerGroupSetCustomTypeAction: !include customer-group/updates/CustomerGroupSetCustomTypeAction.raml
 CustomerGroupSetKeyAction: !include customer-group/updates/CustomerGroupSetKeyAction.raml
+CustomerIndexingProgress: !include customer-search/CustomerIndexingProgress.raml
+CustomerIndexingStatus: !include customer-search/CustomerIndexingStatus.raml
+CustomerPagedSearchResponse: !include customer-search/CustomerPagedSearchResponse.raml
+CustomerSearchIndexingStatusResponse: !include customer-search/CustomerSearchIndexingStatusResponse.raml
+CustomerSearchRequest: !include customer-search/CustomerSearchRequest.raml
+CustomerSearchResult: !include customer-search/CustomerSearchResult.raml
 AnonymousCartSignInMode: !include customer/AnonymousCartSignInMode.raml
 AuthenticationMode: !include customer/AuthenticationMode.raml
 Customer: !include customer/Customer.raml
@@ -489,6 +495,7 @@ BadGatewayError: !include error/BadGatewayError.raml
 ConcurrentModificationError: !include error/ConcurrentModificationError.raml
 ContentTooLargeError: !include error/ContentTooLargeError.raml
 CountryNotConfiguredInStoreError: !include error/CountryNotConfiguredInStoreError.raml
+CustomerSearchProjectNotIndexedError: !include error/CustomerSearchProjectNotIndexedError.raml
 DiscountCodeNonApplicableError: !include error/DiscountCodeNonApplicableError.raml
 DuplicateAttributeValueError: !include error/DuplicateAttributeValueError.raml
 DuplicateAttributeValuesError: !include error/DuplicateAttributeValuesError.raml
@@ -570,6 +577,7 @@ GraphQLBadGatewayError: !include error/graphql/GraphQLBadGatewayError.raml
 GraphQLConcurrentModificationError: !include error/graphql/GraphQLConcurrentModificationError.raml
 GraphQLContentTooLargeError: !include error/graphql/GraphQLContentTooLargeError.raml
 GraphQLCountryNotConfiguredInStoreError: !include error/graphql/GraphQLCountryNotConfiguredInStoreError.raml
+GraphQLCustomerSearchProjectNotIndexedError: !include error/graphql/GraphQLCustomerSearchProjectNotIndexedError.raml
 GraphQLDiscountCodeNonApplicableError: !include error/graphql/GraphQLDiscountCodeNonApplicableError.raml
 GraphQLDuplicateAttributeValueError: !include error/graphql/GraphQLDuplicateAttributeValueError.raml
 GraphQLDuplicateAttributeValuesError: !include error/graphql/GraphQLDuplicateAttributeValuesError.raml
@@ -1888,6 +1896,7 @@ CartClassificationType: !include project/CartClassificationType.raml
 CartScoreType: !include project/CartScoreType.raml
 CartValueType: !include project/CartValueType.raml
 CartsConfiguration: !include project/CartsConfiguration.raml
+CustomerSearchStatus: !include project/CustomerSearchStatus.raml
 ExternalOAuth: !include project/ExternalOAuth.raml
 OrderSearchStatus: !include project/OrderSearchStatus.raml
 ProductSearchIndexingMode: !include project/ProductSearchIndexingMode.raml
@@ -1907,6 +1916,7 @@ ProjectChangeCountriesAction: !include project/updates/ProjectChangeCountriesAct
 # yamllint disable-line rule:line-length
 ProjectChangeCountryTaxRateFallbackEnabledAction: !include project/updates/ProjectChangeCountryTaxRateFallbackEnabledAction.raml
 ProjectChangeCurrenciesAction: !include project/updates/ProjectChangeCurrenciesAction.raml
+ProjectChangeCustomerSearchStatusAction: !include project/updates/ProjectChangeCustomerSearchStatusAction.raml
 ProjectChangeLanguagesAction: !include project/updates/ProjectChangeLanguagesAction.raml
 ProjectChangeMessagesConfigurationAction: !include project/updates/ProjectChangeMessagesConfigurationAction.raml
 ProjectChangeMessagesEnabledAction: !include project/updates/ProjectChangeMessagesEnabledAction.raml