Updated API from documentation release

commercetools · Oct 18, 2023 · da5022e · da5022e
1 parent 00ec179
commit da5022e
Show file tree

Hide file tree

Showing 41 changed files with 1,255 additions and 12 deletions.
diff --git a/api-specs/api/api.raml b/api-specs/api/api.raml
@@ -73,8 +73,6 @@ resourceTypes:
       displayName: Check <<resourcePathName>> are existing
       responses:
         200:
-          description: |
-            At least one <<resourceType>> matching the query exists
         404:
           description: |
             ## Not Found
@@ -124,8 +122,6 @@ resourceTypes:
       displayName: Check <<resourceType>> exists by <<uriParameterName | !lowercamelcase>>
       responses:
         200:
-          description: |
-            The <<resourceType>> exists
         404:
           description: |
             ## Not Found
@@ -167,6 +163,11 @@ resourceTypes:
         body:
           example: !include examples/project.example.json
           type: Project
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_project_settings:{projectKey}'] }]
+    description: Checks if a Project exists for a given `projectKey`. Returns a `200 OK` status if the Project exists or a `404 Not Found` otherwise.
+    responses:
+      200:
   post:
     displayName: Update project settings
     is:

diff --git a/api-specs/api/resources/api-clients.raml b/api-specs/api/resources/api-clients.raml
@@ -14,6 +14,17 @@ get:
       body:
         application/json:
           example: !include ../examples/api-clients.example.json
+head:
+  securedBy: [oauth_2_0: { scopes: ['view_api_clients:{projectKey}'] }]
+  description: Checks if an API Client exists for a given Query Predicate. Returns a `200 OK` status if any API Clients match the Query Predicate or a `404 Not Found` otherwise.
+  queryParameters:
+    where?:
+      type: QueryPredicate[]
+      description: |-
+        Query Predicates on API Clients are limited to [Text](ctp:api:type:AttributeTextType),
+        [Enum](ctp:api:type:AttributeEnumType), [Boolean](ctp:api:type:AttributeBooleanType),
+        [Number](ctp:api:type:AttributeNumberType), [Date](ctp:api:type:AttributeDateType),
+        [Time](ctp:api:type:AttributeTimeType), and [DateTime](ctp:api:type:AttributeDateTimeType) attribute types.
 post:
   securedBy: [oauth_2_0: { scopes: ['manage_api_clients:{projectKey}'] }]
   body:
@@ -41,6 +52,9 @@ post:
           application/json:
             example: !include ../examples/api-client.example.json
             type: ApiClient
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_api_clients:{projectKey}'] }]
+    description: Checks if an API Client exists for a given `id`. Returns a `200 OK` status if the API Client exists or a `404 Not Found` otherwise.
   delete:
     securedBy: [oauth_2_0: { scopes: ['manage_api_clients:{projectKey}'] }]
     displayName: Delete ApiClient by ID

diff --git a/api-specs/api/resources/as-associate.raml b/api-specs/api/resources/as-associate.raml
@@ -25,6 +25,12 @@ type: base
           body:
             application/json:
               example: !include ../examples/business-units.example.json
+    head:
+      securedBy: [oauth_2_0: { scopes: ['view_business_units:{projectKey}'] }]
+      description: Checks if a BusinessUnit exists for a given Query Predicate. Returns a `200 OK` status if any BusinessUnits match the Query Predicate or a `404 Not Found` otherwise.
+      queryParameters:
+        where?:
+          type: QueryPredicate[]
     post:
       securedBy: [oauth_2_0: { scopes: ['manage_business_units:{projectKey}'] }]
       body:
@@ -49,6 +55,9 @@ type: base
             body:
               application/json:
                 example: !include ../examples/business-unit.example.json
+      head:
+        securedBy: [oauth_2_0: { scopes: ['view_business_units:{projectKey}'] }]
+        description: Checks if a BusinessUnit exists for a given `key`. Returns a `200 OK` status if the BusinessUnit exists or a `404 Not Found` otherwise.
       post:
         securedBy:
           [oauth_2_0: { scopes: ['manage_business_units:{projectKey}'] }]
@@ -74,6 +83,9 @@ type: base
             body:
               application/json:
                 example: !include ../examples/business-unit.example.json
+      head:
+        securedBy: [oauth_2_0: { scopes: ['view_business_units:{projectKey}'] }]
+        description: Checks if a BusinessUnit exists for a given `id`. Returns a `200 OK` status if the BusinessUnit exists or a `404 Not Found` otherwise.
       post:
         securedBy:
           [oauth_2_0: { scopes: ['manage_business_units:{projectKey}'] }]
@@ -233,6 +245,12 @@ type: base
             body:
               application/json:
                 example: !include ../examples/b2b-carts.example.json
+      head:
+        securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
+        description: Checks if a Cart exists for a given Query Predicate. Returns a `200 OK` status if any Carts match the Query Predicate or a `404 Not Found` otherwise.
+        queryParameters:
+          where?:
+            type: QueryPredicate[]
       post:
         displayName: Create cart in business unit
         securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
@@ -264,6 +282,9 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/b2b-cart.example.json
+        head:
+          securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
+          description: Checks if a Cart exists for a given `key`. Returns a `200 OK` status if the Cart exists or a `404 Not Found` otherwise.
         post:
           displayName: Update cart by key in business unit
           securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
@@ -305,6 +326,9 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/b2b-cart.example.json
+        head:
+          securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
+          description: Checks if a Cart exists for a given `id`. Returns a `200 OK` status if the Cart exists or a `404 Not Found` otherwise.
         post:
           displayName: Update cart by id in business unit
           securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
@@ -371,6 +395,12 @@ type: base
             body:
               application/json:
                 example: !include ../examples/orders.example.json
+      head:
+        securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
+        description: Checks if an Order exists for a given Query Predicate. Returns a `200 OK` status if any Orders match the Query Predicate or a `404 Not Found` otherwise.
+        queryParameters:
+          where?:
+            type: QueryPredicate[]
       post:
         displayName: Create order from cart in business unit
         securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
@@ -427,6 +457,9 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/order.example.json
+        head:
+          securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
+          description: Checks if an Order exists for a given `orderNumber`. Returns a `200 OK` status if the Order exists or a `404 Not Found` otherwise.
         post:
           displayName: Update order by order number in business unit
           securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
@@ -457,6 +490,9 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/order.example.json
+        head:
+          securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
+          description: Checks if an Order exists for a given `id`. Returns a `200 OK` status if the Order exists or a `404 Not Found` otherwise.
         post:
           displayName: Update order by id in business unit
           securedBy: [oauth_2_0: { scopes: ['manage_orders:{projectKey}'] }]
@@ -489,6 +525,12 @@ type: base
             body:
               application/json:
                 example: !include ../examples/quotes.example.json
+      head:
+        securedBy: [oauth_2_0: { scopes: ['view_quotes:{projectKey}'] }]
+        description: Checks if a Quote exists for a given Query Predicate. Returns a `200 OK` status if any Quotes match the Query Predicate or a `404 Not Found` otherwise.
+        queryParameters:
+          where?:
+            type: QueryPredicate[]
       /key={key}:
         (methodName): withKey
         type:
@@ -505,6 +547,9 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/quote.example.json
+        head:
+          securedBy: [oauth_2_0: { scopes: ['view_quotes:{projectKey}'] }]
+          description: Checks if a Quote exists for a given `key`. Returns a `200 OK` status if the Quote exists or a `404 Not Found` otherwise.
         post:
           securedBy: [oauth_2_0: { scopes: ['manage_quotes:{projectKey}'] }]
           description: |
@@ -533,6 +578,9 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/quote.example.json
+        head:
+          securedBy: [oauth_2_0: { scopes: ['view_quotes:{projectKey}'] }]
+          description: Checks if a Quote exists for a given `id`. Returns a `200 OK` status if the Quote exists or a `404 Not Found` otherwise.
         post:
           securedBy: [oauth_2_0: { scopes: ['manage_quotes:{projectKey}'] }]
           description: |
@@ -563,6 +611,12 @@ type: base
             body:
               application/json:
                 example: !include ../examples/quote-requests.example.json
+      head:
+        securedBy: [oauth_2_0: { scopes: ['view_quote_requests:{projectKey}'] }]
+        description: Checks if a QuoteRequest exists for a given Query Predicate. Returns a `200 OK` status if any QuoteRequests match the Query Predicate or a `404 Not Found` otherwise.
+        queryParameters:
+          where?:
+            type: QueryPredicate[]
       post:
         securedBy:
           [oauth_2_0: { scopes: ['manage_quote_requests:{projectKey}'] }]
@@ -594,6 +648,10 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/quote-request.example.json
+        head:
+          securedBy:
+            [oauth_2_0: { scopes: ['view_quote_requests:{projectKey}'] }]
+          description: Checks if a QuoteRequest exists for a given `key`. Returns a `200 OK` status if the QuoteRequest exists or a `404 Not Found` otherwise.
         post:
           securedBy:
             [oauth_2_0: { scopes: ['manage_quote_requests:{projectKey}'] }]
@@ -624,6 +682,10 @@ type: base
               body:
                 application/json:
                   example: !include ../examples/quote-request.example.json
+        head:
+          securedBy:
+            [oauth_2_0: { scopes: ['view_quote_requests:{projectKey}'] }]
+          description: Checks if a QuoteRequest exists for a given `id`. Returns a `200 OK` status if the QuoteRequest exists or a `404 Not Found` otherwise.
         post:
           securedBy:
             [oauth_2_0: { scopes: ['manage_quote_requests:{projectKey}'] }]

diff --git a/api-specs/api/resources/associate-roles.raml b/api-specs/api/resources/associate-roles.raml
@@ -16,6 +16,12 @@ get:
       body:
         application/json:
           example: !include ../examples/associate-roles.example.json
+head:
+  securedBy: [oauth_2_0: { scopes: ['view_associate_roles:{projectKey}'] }]
+  description: Checks if an AssociateRole exists for a given Query Predicate. Returns a `200 OK` status if any AssociateRole match the Query Predicate or a `404 Not Found` otherwise.
+  queryParameters:
+    where?:
+      type: QueryPredicate[]
 post:
   securedBy: [oauth_2_0: { scopes: ['manage_associate_roles:{projectKey}'] }]
   description: |
@@ -42,6 +48,9 @@ post:
         body:
           application/json:
             example: !include ../examples/associate-role.example.json
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_associate_roles:{projectKey}'] }]
+    description: Checks if an AssociateRole exists for a given `key`. Returns a `200 OK` status if the AssociateRole exists or a `404 Not Found` otherwise.
   post:
     securedBy: [oauth_2_0: { scopes: ['manage_associate_roles:{projectKey}'] }]
     body:
@@ -75,6 +84,9 @@ post:
         body:
           application/json:
             example: !include ../examples/associate-role.example.json
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_associate_roles:{projectKey}'] }]
+    description: Checks if an AssociateRole exists for a given `id`. Returns a `200 OK` status if the AssociateRole exists or a `404 Not Found` otherwise.
   post:
     securedBy: [oauth_2_0: { scopes: ['manage_associate_roles:{projectKey}'] }]
     body:

diff --git a/api-specs/api/resources/attribute-groups.raml b/api-specs/api/resources/attribute-groups.raml
@@ -16,6 +16,17 @@ get:
       body:
         application/json:
           example: !include ../examples/AttributeGroup/AttributeGroups.json
+head:
+  securedBy: [oauth_2_0: { scopes: ['view_attribute_groups:{projectKey}'] }]
+  description: Checks if an AttributeGroup exists for a given Query Predicate. Returns `200 OK` status if any AttributeGroups match the Query Predicate or a `404 Not Found` otherwise.
+  queryParameters:
+    where?:
+      type: QueryPredicate[]
+      description: |-
+        Query Predicates on Attribute Groups are limited to [Text](ctp:api:type:AttributeTextType),
+        [Enum](ctp:api:type:AttributeEnumType), [Boolean](ctp:api:type:AttributeBooleanType),
+        [Number](ctp:api:type:AttributeNumberType), [Date](ctp:api:type:AttributeDateType),
+        [Time](ctp:api:type:AttributeTimeType), and [DateTime](ctp:api:type:AttributeDateTimeType) attribute types.
 post:
   securedBy: [oauth_2_0: { scopes: ['manage_attribute_groups:{projectKey}'] }]
   body:
@@ -40,6 +51,9 @@ post:
         body:
           application/json:
             example: !include ../examples/AttributeGroup/AttributeGroup.json
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_attribute_groups:{projectKey}'] }]
+    description: Checks if an AttributeGroup exists for a given `key`. Returns `200 OK` status if the AttributeGroup exists or a `404 Not Found` otherwise.
   post:
     securedBy: [oauth_2_0: { scopes: ['manage_attribute_groups:{projectKey}'] }]
     body:
@@ -71,6 +85,9 @@ post:
         body:
           application/json:
             example: !include ../examples/AttributeGroup/AttributeGroup.json
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_attribute_groups:{projectKey}'] }]
+    description: Checks if an AttributeGroup exists for a given `id`. Returns a `200 OK` status if the AttributeGroup exists or a `404 Not Found` otherwise.
   post:
     securedBy: [oauth_2_0: { scopes: ['manage_attribute_groups:{projectKey}'] }]
     body:

diff --git a/api-specs/api/resources/business-units.raml b/api-specs/api/resources/business-units.raml
@@ -16,6 +16,12 @@ get:
       body:
         application/json:
           example: !include ../examples/business-units.example.json
+head:
+  securedBy: [oauth_2_0: { scopes: ['view_business_units:{projectKey}'] }]
+  description: Checks if a BusinessUnit exists for a given Query Predicate. Returns a `200 OK` status if any BusinessUnits match the Query Predicate or a `404 Not Found` otherwise.
+  queryParameters:
+    where?:
+      type: QueryPredicate[]
 post:
   securedBy: [oauth_2_0: { scopes: ['manage_business_units:{projectKey}'] }]
   body:
@@ -40,6 +46,9 @@ post:
         body:
           application/json:
             example: !include ../examples/business-unit.example.json
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_business_units:{projectKey}'] }]
+    description: Checks if a BusinessUnit exists for a given `key`. Returns a `200 OK` status if the BusinessUnit exists or a `404 Not Found` otherwise.
   post:
     securedBy: [oauth_2_0: { scopes: ['manage_business_units:{projectKey}'] }]
     body:
@@ -71,6 +80,9 @@ post:
         body:
           application/json:
             example: !include ../examples/business-unit.example.json
+  head:
+    securedBy: [oauth_2_0: { scopes: ['view_business_units:{projectKey}'] }]
+    description: Checks if a BusinessUnit exists for a given `id`. Returns a `200 OK` status if the BusinessUnit exists or a `404 Not Found` otherwise.
   post:
     securedBy: [oauth_2_0: { scopes: ['manage_business_units:{projectKey}'] }]
     body:

diff --git a/api-specs/api/resources/cart-discounts.raml b/api-specs/api/resources/cart-discounts.raml
@@ -25,6 +25,19 @@ get:
       body:
         application/json:
           example: !include ../examples/cart-discounts.example.json
+head:
+  securedBy:
+    [
+      oauth_2_0:
+        {
+          scopes:
+            ['view_orders:{projectKey}', 'view_cart_discounts:{projectKey}'],
+        },
+    ]
+  description: Checks if a CartDiscount exists for a given Query Predicate. Returns a `200 OK` status if any CartDiscounts match the Query Predicate, or a `404 Not Found` otherwise.
+  queryParameters:
+    where?:
+      type: QueryPredicate[]
 post:
   securedBy:
     [
@@ -66,6 +79,16 @@ post:
         body:
           application/json:
             example: !include ../examples/cart-discount.example.json
+  head:
+    securedBy:
+      [
+        oauth_2_0:
+          {
+            scopes:
+              ['view_orders:{projectKey}', 'view_cart_discounts:{projectKey}'],
+          },
+      ]
+    description: Checks if a CartDiscount exists for a given `key`. Returns a `200 OK` status if the CartDiscount exists or a `404 Not Found` otherwise.
   post:
     securedBy:
       [
@@ -124,6 +147,16 @@ post:
         body:
           application/json:
             example: !include ../examples/cart-discount.example.json
+  head:
+    securedBy:
+      [
+        oauth_2_0:
+          {
+            scopes:
+              ['view_orders:{projectKey}', 'view_cart_discounts:{projectKey}'],
+          },
+      ]
+    description: Checks if a CartDiscount exists for a given `id`. Returns a `200 OK` status if the CartDiscount exists or a `404 Not Found` otherwise.
   post:
     securedBy:
       [