Merge pull request #694 from akeneo/new-catalog-endpoint

Catalog documentation cleanup

Author: meganelepalud-akeneo

content/apps/catalogs.md

@@ -29,6 +29,20 @@ To ensure Akeneo PXM Studio remains stable, we added some limits to catalogs:
 - Each app can create up to **15 catalogs**.
 - A product selection can have up to **25 selection criteria**.
 
+### Troubleshooting
+
+#### Automatic deactivation on catalogs
+
+When a product selection becomes invalid, e.g. a selected category no longer exists, the PIM automatically disables the catalog. 
+
+In that case, your app receives an HTTP 200 response containing the following payload.
+
+```json
+{
+  "error": "No products to synchronize. The catalog \"65f5a521-e65c-4d7b-8be8-1f267fa2729c\" has been disabled on the PIM side. Note that you can get catalogs status with the GET /api/rest/v1/catalogs endpoint."
+}
+```
+
 
 ### Next steps
 

content/swagger/parameters.yaml

@@ -121,18 +121,35 @@ with_quality_scores__product_models:
   description: Return product model quality scores in the response. <strong>(Only available on SaaS platforms)</strong>
   type: boolean
   required: false
-  x-from-version: "SaaS"
+  x-from-version: "6.0"
 with_completenesses:
   name: with_completenesses
   in: query
   description: Return product completenesses in the response. (Only available on SaaS platforms)
   default: false
   type: boolean
   required: false
-  x-from-version: "SaaS"
+  x-from-version: "6.0"
 with_position:
   name: with_position
   in: query
   description: Return information about category position into its category tree (only available on SaaS platforms)
   required: false
   type: boolean
+  x-from-version: "SaaS"
+updated_before:
+  name: updated_before
+  in: query
+  description: Filter products that have been updated BEFORE the provided date (Only available on Catalogs endpoints)
+  type: string
+  format: date
+  required: false
+  x-from-version: "SaaS"
+updated_after:
+  name: updated_after
+  in: query
+  description: Filter products that have been updated AFTER the provided date (Only available on Catalogs endpoints)
+  type: string
+  format: date
+  required: false
+  x-from-version: "SaaS"

content/swagger/paths.yaml

@@ -167,6 +167,10 @@
   $ref: ./resources/app_catalogs/routes/app_catalogs_id.yaml
 /api/rest/v1/catalogs/{id}/product-uuids:
   $ref: ./resources/app_catalogs/routes/app_catalogs_id_product_uuids.yaml
+/api/rest/v1/catalogs/{id}/products:
+  $ref: ./resources/app_catalogs/routes/app_catalogs_id_products.yaml
+/api/rest/v1/catalogs/{id}/products/{uuid}:
+  $ref: ./resources/app_catalogs/routes/app_catalogs_id_products_uuid.yaml
 
 /api/rest/v1:
   $ref: ./resources/list_endpoints.yaml

content/swagger/resources/app_catalogs/routes/app_catalogs.yaml

@@ -66,7 +66,7 @@ get:
     401:
       $ref: "#/responses/401Error"
     403:
-      $ref: "#/responses/403Error"
+      $ref: "#/responses/403CatalogError"
 post:
   summary: Create a new catalog
   operationId: "post_app_catalog"
@@ -90,8 +90,27 @@ post:
     401:
       $ref: "#/responses/401Error"
     403:
-      $ref: "#/responses/403Error"
+      $ref: "#/responses/403CatalogError"
     415:
       $ref: "#/responses/415Error"
     422:
-      $ref: "#/responses/422Error"
+      description: Unprocessable entity
+      x-details: The validation of the entity given in the body of the request failed
+      schema:
+        $ref: "#/definitions/Error"
+      x-examples-per-version:
+        - x-version: 'SaaS'
+          x-example: {
+            "code": 422,
+            "message": "Validation failed.",
+            "errors": [
+                {
+                    "property": "name",
+                    "message": "This value should not be blank."
+                },
+                {
+                    "property": "name",
+                    "message": "This value is too short. It should have 1 character or more."
+                }
+            ]
+          }

content/swagger/resources/app_catalogs/routes/app_catalogs_id.yaml

@@ -10,7 +10,7 @@ get:
   parameters:
     - name: id
       in: path
-      description: Id of the catalog
+      description: Catalog ID
       required: true
       type: string
       format: uuid
@@ -22,9 +22,9 @@ get:
     401:
       $ref: "#/responses/401Error"
     403:
-      $ref: "#/responses/403Error"
+      $ref: "#/responses/403CatalogError"
     404:
-      $ref: "#/responses/404Error"
+      $ref: "#/responses/404CatalogError"
 patch:
   summary: Update a catalog
   operationId: "patch_app_catalog"
@@ -37,7 +37,7 @@ patch:
   parameters:
     - name: id
       in: path
-      description: Id of the catalog
+      description: Catalog ID
       required: true
       type: string
       format: uuid
@@ -53,26 +53,45 @@ patch:
     401:
       $ref: "#/responses/401Error"
     403:
-      $ref: "#/responses/403Error"
+      $ref: "#/responses/403CatalogError"
     404:
-      $ref: "#/responses/404Error"
+      $ref: "#/responses/404CatalogError"
     415:
       $ref: "#/responses/415Error"
     422:
-      $ref: "#/responses/422Error"
+      description: Unprocessable entity
+      x-details: The validation of the entity given in the body of the request failed
+      schema:
+        $ref: "#/definitions/Error"
+      x-examples-per-version:
+        - x-version: 'SaaS'
+          x-example: {
+            "code": 422,
+            "message": "Validation failed.",
+            "errors": [
+                {
+                    "property": "name",
+                    "message": "This value should not be blank."
+                },
+                {
+                    "property": "name",
+                    "message": "This value is too short. It should have 1 character or more."
+                }
+            ]
+          }
 delete:
   summary: Delete a catalog
   operationId: "delete_app_catalog"
   tags:
-    - Catalog
+    - Catalogs
   x-versions:
     - "SaaS"
   x-app-token: true
   description: This endpoint allows you to delete a catalog.
   parameters:
     - name: id
       in: path
-      description: Id of the catalog
+      description: Catalog ID
       required: true
       type: string
       format: uuid
@@ -82,6 +101,6 @@ delete:
     401:
       $ref: "#/responses/401Error"
     403:
-      $ref: "#/responses/403Error"
+      $ref: "#/responses/403CatalogError"
     404:
-      $ref: "#/responses/404Error"
+      $ref: "#/responses/404CatalogError"

content/swagger/resources/app_catalogs/routes/app_catalogs_id_product_uuids.yaml

@@ -1,7 +1,8 @@
 get:
   summary: Get the list of product uuids
   operationId: "get_app_catalog_product_uuids"
-  description: Coming soon. This endpoint allows you to get the list of uuids of products contained in a catalog.
+  description: This endpoint allows you to get the list of uuids of products contained in a catalog. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
+    for more details see the <a href="apps/catalogs.html#troubleshooting">App Catalog</a> section.
   tags:
     - Catalog products
   x-versions:
@@ -23,6 +24,8 @@ get:
       minimum: 1
       maximum: 1000
       default: 100
+    - $ref: '#/parameters/updated_before'
+    - $ref: '#/parameters/updated_after'
   responses:
     200:
       description: Return the paginated product uuids
@@ -63,6 +66,6 @@ get:
     401:
       $ref: "#/responses/401Error"
     403:
-      $ref: "#/responses/403Error"
+      $ref: "#/responses/403CatalogError"
     404:
-      $ref: "#/responses/404Error"
+      $ref: "#/responses/404CatalogError"