DEVDOCS-4878: [external] API specs, update Operation IDs to be consis…

…tent & programmatic (#45)  # [DEVDOCS-4878] > As per OpenAPI specification guidance for operationID field, follow programmatic conventions for operationId field. To me that means as if I were defining a method or function name. > This field is not used in the API docs as far as I can tell. There were many different naming conventions across APIs. I've aligned to be camel case. > This helps facilitate API SDK generation as all endpoints can have a function name based on the operation ID and have it have sufficient context to be unique amongst all APIs. ## What changed? * Make operation IDs consistent and follow programmatic conventions ## Release notes draft * A valued partner has put in the heroic work to make the OAS operation IDs programmatic across our public APIs. The operationId property is now consistently camelCase and relates to the plain-language name of the endpoint. Thanks, @bobbyshaw! ## Anything else? * Original PR [bigcommerce/api-specs 1469](bigcommerce/api-specs#1469) * Related Issue [bigcommerce/api-specs 1143](bigcommerce/api-specs#1143) * Tag for last commit before this -- https://github.com/bigcommerce/docs/releases/tag/before-operation-id-change --------- Co-authored-by: Tom Robertshaw <[email protected]>
bigcommerce · Apr 26, 2024 · 7efce03 · 7efce03
1 parent 17a1a24
commit 7efce03
Show file tree

Hide file tree

Showing 52 changed files with 478 additions and 458 deletions.
diff --git a/.spectral.yaml b/.spectral.yaml
@@ -17,7 +17,6 @@ except:
     - oas2-valid-media-example
     - oas2-valid-schema-example
   'reference/channels.v3.yml':
-    - operation-operationId
     - oas3-schema
     - oas3-valid-media-example
   'reference/current_customer.yml':
@@ -26,14 +25,10 @@ except:
     - openapi-tags
     - operation-tag-defined
   'reference/customer_login.yml':
-    - operation-operationId
     - operation-success-response
   'reference/email_templates.v3.yml':
     - oas3-schema
-    - operation-tag-defined
-    - openapi-tags
   'reference/geography.v2.yml':
-    - operation-operationId
     - oas2-valid-media-example
   'reference/orders.v2.oas2.yml':
     - oas3-valid-schema-example
@@ -45,46 +40,34 @@ except:
     - oas2-anyOf
   'reference/settings.v3.yml':
     - oas3-valid-media-example
-    - operation-operationId
   'reference/sites.v3.yml':
     - oas2-valid-media-example
-    - operation-operationId
   'reference/store_information.v2.yml':
     - oas2-valid-media-example
-    - operation-operationId
     - oas2-valid-schema-example
   'reference/themes.v3.yml':
     - oas3-schema
-    - operation-operationId
   'reference/webhooks.v3.yml':
     - oas3-valid-media-example
   'carts.v3.yml':
     - oas2-oneOf
     - oas2-valid-schema-example
-    - operation-tag-defined
   'catalog.v3.yml':
     - oas2-operation-security-defined
     - oas3-schema
     - oas2-schema
     - oas2-valid-media-example
     - oas2-valid-schema-example
   'channels.v3.yml':
-    - operation-operationId
     - oas3-schema
     - oas3-valid-media-example
   'current_customer.yml':
     - operation-success-response
-  'custom-template-associations.v3.yml':
-    - openapi-tags
-    - operation-tag-defined
   'customer_login.yml':
     - operation-success-response
   'email_templates.v3.yml':
     - oas3-schema
-    - operation-tag-defined
-    - openapi-tags
   'geography.v2.yml':
-    - operation-operationId
     - oas2-valid-media-example
   'orders.v2.oas2.yml':
     - oas3-valid-schema-example
@@ -96,17 +79,13 @@ except:
     - oas2-anyOf
   'settings.v3.yml':
     - oas3-valid-media-example
-    - operation-operationId
   'sites.v3.yml':
     - oas2-valid-media-example
-    - operation-operationId
   'store_information.v2.yml':
     - oas2-valid-media-example
-    - operation-operationId
     - oas2-valid-schema-example
   'themes.v3.yml':
     - oas3-schema
-    - operation-operationId
   'webhooks.v3.yml':
     - oas3-valid-media-example
   'pages.v3.yml':

diff --git a/reference/abandoned_cart_emails.v3.yaml b/reference/abandoned_cart_emails.v3.yaml
@@ -57,11 +57,11 @@ paths:
                     meta: {}
       tags:
         - Abandoned Cart Emails
-      summary: Get all email templates
-      operationId: getAbandonedCartEmails
+      summary: Get all abandoned cart email templates
+      operationId: getAbandonedCartEmailTemplates
     post:
-      summary: Create email template
-      operationId: createEmailTemplate
+      summary: Create abandoned cart email template
+      operationId: createAbandonedCartEmailTemplate
       tags:
         - Abandoned Cart Emails
       responses:
@@ -96,7 +96,7 @@ paths:
                   notify_at_minutes: 60
                   template:
                     subject: 'Complete your purchase at {{ store.name }}'
-                    body: '{{lang ''hello_phrase'' }}<br>Complete your purchase <a href="{{ notification.checkout_link }}">{{notification.checkout.link}}'
+                    body: "{{lang 'hello_phrase' }}<br>Complete your purchase <a href='{{ notification.checkout_link }}'>{{notification.checkout.link}}"
                     translations:
                       - locale: en
                         keys:
@@ -124,11 +124,11 @@ paths:
                     $ref: '#/components/schemas/metaCollection_open'
       tags:
         - Abandoned Cart Emails
-      operationId: getAbandonedCartEmailTemplateId
+      operationId: getAbandonedCartEmailTemplate
     put:
       summary: Update an email template
       description: Update an email template.
-      operationId: updateAbandonedCartEmailsId
+      operationId: updateAbandonedCartEmailTemplate
       tags:
         - Abandoned Cart Emails
       responses:
@@ -184,7 +184,7 @@ paths:
         - Abandoned Cart Emails
       description: Delete Abandoned Cart Email template.
       summary: Delete email template
-      operationId: deleteAbandonedCartEmailTemplateId
+      operationId: deleteAbandonedCartEmailTemplate
       responses:
         '204':
           description: No Content
@@ -203,7 +203,7 @@ paths:
       description: Return default Abandoned Cart Email template.
       tags:
         - Abandoned Cart Emails
-      operationId: GetDefaultAbandonedCartEmailTemplate
+      operationId: getDefaultAbandonedCartEmailTemplate
       responses:
         '200':
           description: OK
@@ -264,13 +264,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AbandonedCartSettings'
-      operationId: GetAbandonedCartEmailTemplateSettings
+      operationId: getAbandonedCartEmailTemplateSettings
       description: Read Abandoned Cart Email Template settings.
       parameters:
         - $ref: '#/components/parameters/ChannelIdRequired'
     put:
       summary: Update email template settings
-      operationId: updateEmailTemplateSettings
+      operationId: updateAbandonedCartEmailTemplateSettings
       tags:
         - Template settings
       responses:
@@ -379,12 +379,13 @@ components:
         locale:
           type: string
           example: en
-          description: 'Locale code for this language, such as ''en'', ''en-us'', ''fr-ca''.'
+          description: "Locale code for this language, such as 'en', 'en-us', 'fr-ca'."
         keys:
-          type: string
+          type: object
           description: Language keys for the template. User-defined. Should match any language keys used in the template.
-        additionalProperties:
-          type: string
+          properties: {}
+          additionalProperties:
+            type: string
       required:
         - locale
         - keys

diff --git a/reference/abandoned_carts.v3.yml b/reference/abandoned_carts.v3.yml
@@ -47,7 +47,7 @@ paths:
     put:
       summary: Update Global Abandoned Cart Settings
       description: Updates the global abandoned cart settings of a store.
-      operationId: UpdateGlobalAbandonedCartSettings
+      operationId: updateGlobalAbandonedCartSettings
       tags:
         - Abandoned Carts Settings
       requestBody:
@@ -109,7 +109,7 @@ paths:
         | UI Name                                      | Permission | Parameter                                     |
         |----------------------------------------------|------------|-----------------------------------------------|     
         | Information & Settings                       | modify     | `store_v2_information`                        |
-      operationId: UpdateChannelAbandonedCartSettings
+      operationId: updateChannelAbandonedCartSettings
       tags:
         - Abandoned Carts Settings
       parameters:

diff --git a/reference/carts.sf.yml b/reference/carts.sf.yml
@@ -36,7 +36,7 @@ paths:
         > * Substitute your storefront domain for `yourstore.example.com`. 
         > * The Send a Test Request feature is not currently supported for this endpoint.  
 
-      operationId: getACart
+      operationId: getCart
       parameters:
         - $ref: '#/components/parameters/include'
       responses:
@@ -53,7 +53,7 @@ paths:
         > * Substitute your storefront domain for `yourstore.example.com`. 
         > * The Send a Test Request feature is not currently supported for this endpoint.  
 
-      operationId: createACart
+      operationId: createCart
       parameters:
         - $ref: '#/components/parameters/include'
       requestBody:
@@ -103,7 +103,7 @@ paths:
         > * Substitute your storefront domain for `yourstore.example.com`. 
         > * The Send a Test Request feature is not currently supported for this endpoint.  
 
-      operationId: deleteACart
+      operationId: deleteCart
       parameters:
         - name: cartId
           in: path
@@ -342,7 +342,7 @@ paths:
         > #### Note
         > * Substitute your storefront domain for `yourstore.example.com`. 
         > * The Send a Test Request feature is not currently supported for this endpoint.  
-      operationId: addCartCurrency
+      operationId: updateCartCurrency
       parameters:
         - name: cartId
           in: path

diff --git a/reference/carts.v3.yml b/reference/carts.v3.yml
@@ -271,7 +271,7 @@ paths:
         '201':
           $ref: '#/components/responses/CartResponse'
       summary: Create a Cart
-      operationId: createACart
+      operationId: createCart
   '/carts/{cartId}/items':
     parameters:
       - $ref: '#/components/parameters/cartId'
@@ -346,7 +346,7 @@ paths:
         '201':
           $ref: '#/components/responses/CartResponse'
       summary: Add Cart Line Items
-      operationId: addCartLineItem
+      operationId: addCartLineItems
   '/carts/{cartId}/redirect_urls':
     parameters:
       - $ref: '#/components/parameters/cartId'
@@ -558,7 +558,7 @@ paths:
         '404':
           description: Cart not found.
       summary: Get a Cart
-      operationId: getACart
+      operationId: getCart
     put:
       description: |-
         Updates a *Cart's* `customer_id`.
@@ -596,7 +596,7 @@ paths:
         '201':
           $ref: '#/components/responses/CartResponse'
       summary: Update Customer ID
-      operationId: updateACart
+      operationId: updateCart
     delete:
       description: Deletes a *Cart*. Once a *Cart* has been deleted it can’t be recovered.
       tags:
@@ -605,7 +605,7 @@ paths:
         '204':
           description: ''
       summary: Delete a Cart
-      operationId: deleteACart
+      operationId: deleteCart
   '/carts/settings':
     parameters: 
       - $ref: '#/components/parameters/Accept'
@@ -816,7 +816,7 @@ paths:
         Create a cart `Metafield`. 
 
         If you create an order from a Cart, you can continue referencing the Cart Metafields even if you delete the original Cart. Use the `cart_id` field on the Order to construct the Cart Metafield endpoint. 
-      operationId: CreateCartMetafieldsByCartId
+      operationId: createCartMetafield
       parameters: 
         - $ref: '#/components/parameters/ContentType'
       requestBody:
@@ -874,7 +874,7 @@ paths:
       tags:
         - Metafields
       description: Gets a cart metafield.
-      operationId: getACartMetafield
+      operationId: getCartMetafield
       responses:
         '200':
           description: |
@@ -911,7 +911,7 @@ paths:
         - Metafields
       description: |
         Update a `Metafield`, by `cart_id`.
-      operationId: UpdateCartMetafieldsByCartId
+      operationId: updateCartMetafield
       parameters:
         - $ref: '#/components/parameters/ContentType'
       requestBody:
@@ -951,7 +951,7 @@ paths:
         - Metafields
       description: |
         Deletes a `Metafield`.
-      operationId: deleteCartMetafieldById
+      operationId: deleteCartMetafield
       responses:
         '204':
           description: |

diff --git a/reference/catalog/brands_catalog.v3.yml b/reference/catalog/brands_catalog.v3.yml
@@ -966,7 +966,7 @@ paths:
         - Brands
       summary: Delete a Brand
       description: Deletes a *Brand*.
-      operationId: deleteBrandById
+      operationId: deleteBrand
       responses:
         '204':
           description: ''
@@ -980,7 +980,7 @@ paths:
         - Metafields
       summary: Get All Brand Metafields
       description: 'Returns a list of *Brand Metafields*. Optional filter parameters can be passed in. '
-      operationId: getBrandMetafieldsByBrandId
+      operationId: getBrandMetafields
       parameters:
         - name: id
           in: query
@@ -1281,7 +1281,7 @@ paths:
         - Metafields
       summary: Get a Brand Metafields
       description: Returns a *Brand Metafield*. Optional filter parameters can be passed in.
-      operationId: getBrandMetafieldByBrandId
+      operationId: getBrandMetafield
       parameters:
         - name: metafield_id
           in: path
@@ -1436,7 +1436,7 @@ paths:
         - Metafields
       summary: Delete a Brand Metafield
       description: Deletes a *Brand Metafield*.
-      operationId: deleteBrandMetafieldById
+      operationId: deleteBrandMetafield
       parameters:
         - name: metafield_id
           in: path