Skip to content
This repository has been archived by the owner on Jan 15, 2024. It is now read-only.

Update Operation IDs to be consistent & programmatic #1469

Closed

Conversation

bobbyshaw
Copy link
Contributor

[DEVDOCS-]

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.

Screenshot 2023-09-17 at 20 44 14

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 help facilitate API SDK generation as all endpoints can have a function named
based on the operation ID and it have sufficient context to be unique amongst all APIs

What changed?

Provide a bulleted list in the present tense

  • Make operation IDs consistent and follow programmatic conventions

bobbyshaw and others added 3 commits September 16, 2023 12:35
Otherwise OpenAPI parsing error is:

Colons must be followed by a space or an indication character (i.e. " ", ",", "[", "]", "{", "}") at line 2195 (near "value: {\"originalName\":\"BigCommerceLogo.jpeg\",\"temporaryPath\":\"121_fbfb71dfc5a5d911f62d8e35dedd6e45.jpeg\",\"path\":\"f606efcae7e179970b19c3658142c5d0.jpeg\"}").
…conventions.

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 help facilitate API SDK generation as all endpoints can have a function named
based on the operation ID and it have sufficient context to be unique amongst all APIs
@slsriehl
Copy link
Contributor

@bobbyshaw this is tremendous. thank you!

@markcmurphy, @bc-shawnyap, @becomevocal -- can you confirm that this will not break the parser, the request runner, or any other Dev Center functionality?

@slsriehl
Copy link
Contributor

@slsriehl slsriehl closed this Dec 28, 2023
slsriehl pushed a commit to bigcommerce/docs that referenced this pull request Jan 15, 2024
…tent & programmatic (#45)

<!-- Ticket number or summary of work -->
# [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]>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants