From 4d52d5becc97d59426f2b99f74341de021da7b5b Mon Sep 17 00:00:00 2001 From: jordanarldt Date: Thu, 31 Aug 2023 10:52:00 -0500 Subject: [PATCH 01/11] STRF-11160: [new] Add documentation for Redirect Import/Export v3 API --- reference/redirects.v3.yml | 292 +++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 7d68dca53..200a2bdd2 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -20,6 +20,7 @@ security: - X-Auth-Token: [] tags: - name: Redirects + - name: Redirect Import/Export paths: '/storefront/redirects': parameters: @@ -155,6 +156,217 @@ paths: '204': description: No Content content: {} + '/storefront/redirects/imex/jobs': + parameters: + - $ref: '#/components/parameters/Accept' + get: + tags: + - Redirect Import/Export + summary: Get Redirect Import/Export Jobs + description: Returns a collection of the store's 301 redirects across all sites. + operationId: GetRedirectImportExportJobs + parameters: + - name: id + in: query + description: Filters results by redirect import/export job id. + style: form + explode: false + schema: + type: string + - name: type + in: query + description: Filters results by redirect import/export job type. + style: form + explode: false + schema: + $ref: '#/components/schemas/ImportExportJobType' + - name: status + in: query + description: Filters results by redirect import/export job status. + style: form + explode: false + schema: + $ref: '#/components/schemas/ImportExportJobStatus' + - name: limit + in: query + description: Controls the number of items to return per page. + schema: + type: integer + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of items. Used to paginate large collections. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/301RedirectImportExportJobRead' + meta: + $ref: '#/components/schemas/MetaPaginationObject' + '/storefront/redirects/imex/export': + parameters: + - $ref: '#/components/parameters/Accept' + post: + tags: + - Redirect Import/Export + summary: Create Redirects Export + description: Creates a new 301 Redirects Export job. + operationId: CreateRedirectExportJob + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + type: object + properties: + site_id: + type: integer + nullable: true + default: null + description: The site ID to export redirects for. If not provided, all redirects for all sites will be exported. + redirect_ids: + type: array + items: + type: integer + default: [] + description: List of redirect IDs to export. If not provided, all redirects for the given site selection will be exported. + description: 'Data necessary to create a new 301 Redirects Export job.' + required: true + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 + default: empty + '429': + description: Your store already has an active import or export job running. + '409': + description: There are no redirects to export from your store with the provided parameters. + '/storefront/redirects/imex/import': + parameters: + - $ref: '#/components/parameters/Accept' + post: + tags: + - Redirect Import/Export + summary: Create Redirects Import + description: Creates a new 301 Redirects Import job. + operationId: CreateRedirectImportJob + parameters: + - $ref: '#/components/parameters/ContentTypeFormData' + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + import_file: + description: The CSV file containing 301 Redirects to be imported. + type: string + format: binary + required: + - import_file + description: 'Data necessary to create a new 301 Redirects Import job.' + required: true + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 + default: empty + '400': + description: The provided form data was invalid or the file is not a CSV. + '413': + description: The provided file is too large. The maximum file size is 20MB. + '429': + description: Your store already has an active import or export job running. + '/storefront/redirects/imex/export/{uuid}/events': + parameters: + - $ref: '#/components/parameters/AcceptEventStream' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Redirect Import/Export + summary: Get Redirect Export Events + description: Opens an event stream to receive live updates from an export job. + operationId: GetRedirectExportEvents + responses: + '200': + description: Stream of export events + content: + text/event-stream: + schema: + type: string + example: | + event: message + data: {"job_id":"cfccdd6e-956e-4484-8cc2-a610db26bad9","status":"complete","completed_items":100,"total_items":100} + '404': + description: The provided export job ID does not exist. + '/storefront/redirects/imex/import/{uuid}/events': + parameters: + - $ref: '#/components/parameters/AcceptEventStream' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Redirect Import/Export + summary: Get Redirect Import Events + description: Opens an event stream to receive live updates from an import job. + operationId: GetRedirectImportEvents + responses: + '200': + description: Stream of import events + content: + text/event-stream: + schema: + type: string + example: | + event: message + data: {{"job_id":"a4abaf59-9c25-4f37-a09d-66e6054229a1","status":"complete","completed_items":100,"failed_items":100,"total_items":93,"errors":[]} + '404': + description: The provided import job ID does not exist. + '/storefront/redirects/imex/export/{uuid}/download': + parameters: + - $ref: '#/components/parameters/ContentTypeCsv' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Redirect Import/Export + summary: Download Redirect Export + description: Downloads the CSV file containing the results of an export job. + operationId: DownloadRedirectExport + responses: + '200': + description: The exported redirects CSV data + content: + text/csv: + schema: + type: string + format: binary + example: | + Domain,Old Path,New URL/Path,Target Type,Target ID + your-store.com,/old-path,/redirect-target,, + '404': + description: The requested export download does not exist. components: parameters: Accept: @@ -165,6 +377,14 @@ components: schema: type: string default: 'application/json' + AcceptEventStream: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'text/event-stream' ContentType: name: Content-Type in: header @@ -173,6 +393,29 @@ components: schema: type: string default: 'application/json' + ContentTypeFormData: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'multipart/form-data' + ContentTypeCsv: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'text/csv' + ImportExportIdParam: + name: uuid + description: The import/export job identifier. + in: path + required: true + schema: + type: string schemas: Error: type: object @@ -240,6 +483,55 @@ components: description: Full destination URL for the redirect. Must be explicitly included via URL parameter. format: uri example: 'https://store-domain.com/new-url' + ImportExportJobType: + type: string + enum: + - import + - export + ImportExportJobStatus: + type: string + enum: + - new + - working + - complete + - aborted + - failed + ImportErrors: + type: array + items: + type: object + description: 'Detail of an error that occurred during an import job.' + x-internal: false + properties: + row: + type: integer + message: + type: string + 301RedirectImportExportJobRead: + type: object + description: 'Full detail of a Redirect Import/Export job.' + x-internal: false + properties: + id: + type: string + type: + $ref: '#/components/schemas/ImportExportJobType' + status: + $ref: '#/components/schemas/ImportExportJobStatus' + completed_items: + type: integer + failed_items: + type: integer + total_items: + type: integer + errors: + $ref: '#/components/schemas/ImportErrors' + created_at: + description: 'The date-time that the import/export job was created, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + example: '2022-01-04T04:15:50.000Z' + completed_at: + description: 'The date-time that the import/export job was completed, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + example: '2022-01-04T04:15:50.000Z' MetaPaginationObject: type: object properties: From 03de2223cd546883b648ba571228238b302b24c6 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 10:43:36 -0500 Subject: [PATCH 02/11] quotes and caps --- reference/redirects.v3.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 200a2bdd2..b57098c10 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -29,7 +29,7 @@ paths: tags: - Redirects summary: Get Redirects - description: Returns a collection of the store's 301 redirects across all sites. + description: Returns a collection of the storeʼs 301 redirects across all sites. operationId: GetRedirects parameters: - name: site_id @@ -163,12 +163,12 @@ paths: tags: - Redirect Import/Export summary: Get Redirect Import/Export Jobs - description: Returns a collection of the store's 301 redirects across all sites. + description: Returns a collection of the storeʼs 301 redirects across all sites. operationId: GetRedirectImportExportJobs parameters: - name: id in: query - description: Filters results by redirect import/export job id. + description: Filters results by redirect import/export job ID. style: form explode: false schema: @@ -462,11 +462,11 @@ components: type: integer to: $ref: '#/components/schemas/RedirectTo' - description: 'Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data.' + description: Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data. x-internal: false 301RedirectRead: type: object - description: 'Full detail of a Redirect, optionally including the full destination URL.' + description: Full detail of a Redirect, optionally including the full destination URL. x-internal: false properties: id: From 6c93852a99f60ede985f7c6e0a3d2968ec2c38c1 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 10:44:11 -0500 Subject: [PATCH 03/11] update tag to remove slash --- reference/redirects.v3.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index b57098c10..79eead456 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -20,7 +20,7 @@ security: - X-Auth-Token: [] tags: - name: Redirects - - name: Redirect Import/Export + - name: Redirect Import-Export paths: '/storefront/redirects': parameters: @@ -161,7 +161,7 @@ paths: - $ref: '#/components/parameters/Accept' get: tags: - - Redirect Import/Export + - Redirect Import-Export summary: Get Redirect Import/Export Jobs description: Returns a collection of the storeʼs 301 redirects across all sites. operationId: GetRedirectImportExportJobs @@ -216,7 +216,7 @@ paths: - $ref: '#/components/parameters/Accept' post: tags: - - Redirect Import/Export + - Redirect Import-Export summary: Create Redirects Export description: Creates a new 301 Redirects Export job. operationId: CreateRedirectExportJob @@ -262,7 +262,7 @@ paths: - $ref: '#/components/parameters/Accept' post: tags: - - Redirect Import/Export + - Redirect Import-Export summary: Create Redirects Import description: Creates a new 301 Redirects Import job. operationId: CreateRedirectImportJob @@ -306,7 +306,7 @@ paths: - $ref: '#/components/parameters/ImportExportIdParam' get: tags: - - Redirect Import/Export + - Redirect Import-Export summary: Get Redirect Export Events description: Opens an event stream to receive live updates from an export job. operationId: GetRedirectExportEvents @@ -328,7 +328,7 @@ paths: - $ref: '#/components/parameters/ImportExportIdParam' get: tags: - - Redirect Import/Export + - Redirect Import-Export summary: Get Redirect Import Events description: Opens an event stream to receive live updates from an import job. operationId: GetRedirectImportEvents @@ -350,7 +350,7 @@ paths: - $ref: '#/components/parameters/ImportExportIdParam' get: tags: - - Redirect Import/Export + - Redirect Import-Export summary: Download Redirect Export description: Downloads the CSV file containing the results of an export job. operationId: DownloadRedirectExport From b18abdbceb0afc766da96111b72b4bc3e11f53cd Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 10:44:34 -0500 Subject: [PATCH 04/11] revise operationIds --- reference/redirects.v3.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 79eead456..a9fabd5c6 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -164,7 +164,7 @@ paths: - Redirect Import-Export summary: Get Redirect Import/Export Jobs description: Returns a collection of the storeʼs 301 redirects across all sites. - operationId: GetRedirectImportExportJobs + operationId: getRedirectImportExportJobs parameters: - name: id in: query @@ -219,7 +219,7 @@ paths: - Redirect Import-Export summary: Create Redirects Export description: Creates a new 301 Redirects Export job. - operationId: CreateRedirectExportJob + operationId: createRedirectExportJob parameters: - $ref: '#/components/parameters/ContentType' requestBody: @@ -265,7 +265,7 @@ paths: - Redirect Import-Export summary: Create Redirects Import description: Creates a new 301 Redirects Import job. - operationId: CreateRedirectImportJob + operationId: createRedirectImportJob parameters: - $ref: '#/components/parameters/ContentTypeFormData' requestBody: @@ -309,7 +309,7 @@ paths: - Redirect Import-Export summary: Get Redirect Export Events description: Opens an event stream to receive live updates from an export job. - operationId: GetRedirectExportEvents + operationId: getRedirectExportEvents responses: '200': description: Stream of export events @@ -331,7 +331,7 @@ paths: - Redirect Import-Export summary: Get Redirect Import Events description: Opens an event stream to receive live updates from an import job. - operationId: GetRedirectImportEvents + operationId: getRedirectImportEvents responses: '200': description: Stream of import events @@ -353,7 +353,7 @@ paths: - Redirect Import-Export summary: Download Redirect Export description: Downloads the CSV file containing the results of an export job. - operationId: DownloadRedirectExport + operationId: getRedirectExportDownload responses: '200': description: The exported redirects CSV data From a9c915e718a33e8e06de468c876d88cdd6ae6bfb Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 15:42:53 -0500 Subject: [PATCH 05/11] edit endpoint titles (summaries) --- reference/redirects.v3.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index a9fabd5c6..a4c0e0090 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -162,7 +162,7 @@ paths: get: tags: - Redirect Import-Export - summary: Get Redirect Import/Export Jobs + summary: Get Redirect Import-Export Jobs description: Returns a collection of the storeʼs 301 redirects across all sites. operationId: getRedirectImportExportJobs parameters: @@ -217,7 +217,7 @@ paths: post: tags: - Redirect Import-Export - summary: Create Redirects Export + summary: Create Redirects Export Job description: Creates a new 301 Redirects Export job. operationId: createRedirectExportJob parameters: @@ -263,7 +263,7 @@ paths: post: tags: - Redirect Import-Export - summary: Create Redirects Import + summary: Create Redirects Import Job description: Creates a new 301 Redirects Import job. operationId: createRedirectImportJob parameters: @@ -307,7 +307,7 @@ paths: get: tags: - Redirect Import-Export - summary: Get Redirect Export Events + summary: Open Redirect Export Event Stream description: Opens an event stream to receive live updates from an export job. operationId: getRedirectExportEvents responses: @@ -329,7 +329,7 @@ paths: get: tags: - Redirect Import-Export - summary: Get Redirect Import Events + summary: Open Redirect Import Event Stream description: Opens an event stream to receive live updates from an import job. operationId: getRedirectImportEvents responses: From 13d1e92995ff76ea74203649d199e59f98bc5f07 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 15:44:23 -0500 Subject: [PATCH 06/11] remove unnecessary properties --- reference/redirects.v3.yml | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index a4c0e0090..7b8b9c63c 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -252,7 +252,6 @@ paths: id: type: string example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 - default: empty '429': description: Your store already has an active import or export job running. '409': @@ -293,7 +292,6 @@ paths: id: type: string example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 - default: empty '400': description: The provided form data was invalid or the file is not a CSV. '413': @@ -424,31 +422,26 @@ components: type: integer message: type: string - x-internal: false ErrorResponse400: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse404: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse409: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse422: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false 301RedirectUpsert: required: - from_path @@ -463,11 +456,9 @@ components: to: $ref: '#/components/schemas/RedirectTo' description: Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data. - x-internal: false 301RedirectRead: type: object description: Full detail of a Redirect, optionally including the full destination URL. - x-internal: false properties: id: type: integer @@ -501,7 +492,6 @@ components: items: type: object description: 'Detail of an error that occurred during an import job.' - x-internal: false properties: row: type: integer @@ -510,7 +500,6 @@ components: 301RedirectImportExportJobRead: type: object description: 'Full detail of a Redirect Import/Export job.' - x-internal: false properties: id: type: string @@ -567,7 +556,6 @@ components: current: type: string example: '?limit=5&page=1' - x-internal: false RedirectTo: title: RedirectTo type: object @@ -587,13 +575,11 @@ components: maxLength: 2048 type: string example: /new-url/ - x-internal: false DetailedErrors: type: object properties: {} additionalProperties: true title: Detailed Errors - x-internal: false BaseError: type: object properties: @@ -611,7 +597,6 @@ components: type: string description: | Error payload for the BigCommerce API. - x-internal: false ErrorResponse: allOf: - $ref: '#/components/schemas/BaseError' @@ -619,7 +604,6 @@ components: properties: errors: $ref: '#/components/schemas/DetailedErrors' - x-internal: false securitySchemes: X-Auth-Token: name: X-Auth-Token From bebdd5b88682ac41e29b08a7868fb9558e94ce2a Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 15:55:33 -0500 Subject: [PATCH 07/11] update descriptions and orthography --- reference/redirects.v3.yml | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 7b8b9c63c..19189ba73 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -168,33 +168,33 @@ paths: parameters: - name: id in: query - description: Filters results by redirect import/export job ID. + description: Filters results by Redirect Import-Export job ID. style: form explode: false schema: type: string - name: type in: query - description: Filters results by redirect import/export job type. + description: Filters results by the type of the Redirect Import-Export job. style: form explode: false schema: $ref: '#/components/schemas/ImportExportJobType' - name: status in: query - description: Filters results by redirect import/export job status. + description: Filters results by the status of the Redirect Import-Export job. style: form explode: false schema: $ref: '#/components/schemas/ImportExportJobStatus' - name: limit in: query - description: Controls the number of items to return per page. + description: Determines the number of items returned per page. schema: type: integer - name: page in: query - description: Specifies the page number in a limited (paginated) list of items. Used to paginate large collections. + description: Specifies the page number to return when the number of items returned exceeds the page limit. Used to paginate large collections. schema: type: integer responses: @@ -218,7 +218,7 @@ paths: tags: - Redirect Import-Export summary: Create Redirects Export Job - description: Creates a new 301 Redirects Export job. + description: Creates a new 301 Redirects export job. operationId: createRedirectExportJob parameters: - $ref: '#/components/parameters/ContentType' @@ -232,14 +232,14 @@ paths: type: integer nullable: true default: null - description: The site ID to export redirects for. If not provided, all redirects for all sites will be exported. + description: The site ID for which you wish to export redirects. If no site ID is provided, the request exports all redirects for all sites. redirect_ids: type: array items: type: integer default: [] - description: List of redirect IDs to export. If not provided, all redirects for the given site selection will be exported. - description: 'Data necessary to create a new 301 Redirects Export job.' + description: A list of the redirect IDs you wish to export. If no redirect IDs are provided, the request exports all redirects for the given site selection. + description: Data necessary to create a new 301 Redirects export job. required: true responses: '201': @@ -253,9 +253,9 @@ paths: type: string example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 '429': - description: Your store already has an active import or export job running. + description: Your store already has an active Redirects import or export job running. '409': - description: There are no redirects to export from your store with the provided parameters. + description: No Redirects in your store meet the criteria in your request. '/storefront/redirects/imex/import': parameters: - $ref: '#/components/parameters/Accept' @@ -263,7 +263,7 @@ paths: tags: - Redirect Import-Export summary: Create Redirects Import Job - description: Creates a new 301 Redirects Import job. + description: Creates a new 301 Redirects import job. operationId: createRedirectImportJob parameters: - $ref: '#/components/parameters/ContentTypeFormData' @@ -274,12 +274,12 @@ paths: type: object properties: import_file: - description: The CSV file containing 301 Redirects to be imported. + description: A CSV file containing a list of Redirects to be imported. type: string format: binary required: - import_file - description: 'Data necessary to create a new 301 Redirects Import job.' + description: Data necessary to create a new 301 Redirects import job. required: true responses: '201': @@ -297,7 +297,7 @@ paths: '413': description: The provided file is too large. The maximum file size is 20MB. '429': - description: Your store already has an active import or export job running. + description: Your store already has an active Redirects import or export job running. '/storefront/redirects/imex/export/{uuid}/events': parameters: - $ref: '#/components/parameters/AcceptEventStream' @@ -354,7 +354,7 @@ paths: operationId: getRedirectExportDownload responses: '200': - description: The exported redirects CSV data + description: The exported Redirects in CSV format content: text/csv: schema: @@ -409,7 +409,7 @@ components: default: 'text/csv' ImportExportIdParam: name: uuid - description: The import/export job identifier. + description: The import-export job identifier. in: path required: true schema: @@ -491,7 +491,7 @@ components: type: array items: type: object - description: 'Detail of an error that occurred during an import job.' + description: Detail of an error that occurred during an import job. properties: row: type: integer @@ -499,7 +499,7 @@ components: type: string 301RedirectImportExportJobRead: type: object - description: 'Full detail of a Redirect Import/Export job.' + description: Full detail of a Redirect Import-Export job. properties: id: type: string From a7a830d171502cd0a9f603121dc2832c711f2bbe Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 15:56:05 -0500 Subject: [PATCH 08/11] add more detail about schemas --- reference/redirects.v3.yml | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 19189ba73..256bfa457 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -414,6 +414,7 @@ components: required: true schema: type: string + format: uuid schemas: Error: type: object @@ -495,6 +496,7 @@ components: properties: row: type: integer + description: The row in the import CSV where the error occurred. message: type: string 301RedirectImportExportJobRead: @@ -503,23 +505,32 @@ components: properties: id: type: string + format: uuid + description: The Import-Export job ID. type: $ref: '#/components/schemas/ImportExportJobType' status: $ref: '#/components/schemas/ImportExportJobStatus' completed_items: type: integer + description: The number of items that were successfully imported or exported. failed_items: type: integer + description: The number of items that were not successfully imported or exported. total_items: type: integer + description: The number of items in the import or export job. errors: $ref: '#/components/schemas/ImportErrors' created_at: - description: 'The date-time that the import/export job was created, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + type: string + format: date-time + description: 'The date-time that the import-export job was created, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' example: '2022-01-04T04:15:50.000Z' completed_at: - description: 'The date-time that the import/export job was completed, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + type: string + format: date-time + description: 'The date-time that the import-export job was completed, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' example: '2022-01-04T04:15:50.000Z' MetaPaginationObject: type: object From 6492aca2bfcb29954e8a8e884798cd3071bec526 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 16:50:06 -0500 Subject: [PATCH 09/11] update stream examples --- reference/redirects.v3.yml | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 256bfa457..cbe264c37 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -310,14 +310,12 @@ paths: operationId: getRedirectExportEvents responses: '200': - description: Stream of export events + description: Stream of export events. The `data` attribute is stringified JSON. content: text/event-stream: schema: type: string - example: | - event: message - data: {"job_id":"cfccdd6e-956e-4484-8cc2-a610db26bad9","status":"complete","completed_items":100,"total_items":100} + example: 'event: message\ndata: {"job_id":"cfccdd6e-956e-4484-8cc2-a610db26bad9","status":"complete","completed_items":100,"total_items":100}\n\n' '404': description: The provided export job ID does not exist. '/storefront/redirects/imex/import/{uuid}/events': @@ -332,14 +330,12 @@ paths: operationId: getRedirectImportEvents responses: '200': - description: Stream of import events + description: Stream of import events. The `data` attribute is stringified JSON. content: text/event-stream: schema: type: string - example: | - event: message - data: {{"job_id":"a4abaf59-9c25-4f37-a09d-66e6054229a1","status":"complete","completed_items":100,"failed_items":100,"total_items":93,"errors":[]} + example: 'event: message\ndata: {{"job_id":"a4abaf59-9c25-4f37-a09d-66e6054229a1","status":"complete","completed_items":100,"failed_items":100,"total_items":93,"errors":[]}\n\n' '404': description: The provided import job ID does not exist. '/storefront/redirects/imex/export/{uuid}/download': From f6f2d20fe4840478de7dfdea085eb8bb35b3a4c7 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 17:23:53 -0500 Subject: [PATCH 10/11] add limit default --- reference/redirects.v3.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index cbe264c37..3ddd9f9c8 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -189,9 +189,10 @@ paths: $ref: '#/components/schemas/ImportExportJobStatus' - name: limit in: query - description: Determines the number of items returned per page. + description: Determines the number of items returned per page. The default is 10 items per page. schema: type: integer + default: 10 - name: page in: query description: Specifies the page number to return when the number of items returned exceeds the page limit. Used to paginate large collections. From 9b7106e2209863bf997246fd5a7bca5deddd8da1 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 19 Sep 2023 17:24:19 -0500 Subject: [PATCH 11/11] update CSV description and example --- reference/redirects.v3.yml | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 3ddd9f9c8..0ab5bda4b 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -275,9 +275,24 @@ paths: type: object properties: import_file: - description: A CSV file containing a list of Redirects to be imported. + description: |- + A CSV file containing a list of Redirects to be imported. + + The headers must be defined as follows: + + `Domain,Old Path,New URL/Path,Target Type,Target ID` + + Not every line will have a value for every column. type: string format: binary + example: |- + Domain,Old Path,New URL/Path,Target Type,Target ID + store.example.com,/old-path,/new-manual-path,, + store.example.com,/old-product,,Product,12 + store.example.com,/old-brand,,Brand,34 + store.example.com,/old-category,,Category,56 + store.example.com,/old-page,,Page,78 + store.example.com,/old-post,,Post,90 required: - import_file description: Data necessary to create a new 301 Redirects import job. @@ -359,7 +374,7 @@ paths: format: binary example: | Domain,Old Path,New URL/Path,Target Type,Target ID - your-store.com,/old-path,/redirect-target,, + store.example.com,/old-path,/redirect-target,, '404': description: The requested export download does not exist. components: