Use operationId for #anchor tags of REST API endpoint titles

[gr2m]

What feature or product is affected?

• REST API

What is the new or expected behavior?

Example

https://docs.github.com/en/rest/reference/repos#check-if-vulnerability-alerts-are-enabled-for-a-repository

would become

https://docs.github.com/en/rest/reference/repos#check-vulnerability-alerts

See OpenAPI spec at https://github.com/github/openapi/blob/347c7c385184352692d4118b7e8a266ccf9b7db7/definitions/operations/repos/check-vulnerability-alerts.yml#L6

How is the old or inaccurate behavior currently documented?

n/a

Who does this affect?

Every change to an #anchor name for endpoint titles requires a change in the code, due to the error handlers which include a URL to the documentation. The endpoint titles are more prone to changes, while operation IDs should be changed much less frequently, as they are consider a breaking change to some of the OpenAPI consumers, while the "summary" key is not.

The problem with the title changes might also be amplified once translations are introduced.

@zeke sent me here, we shortly discussed it today:

What is the impact to users?

n/a

Content strategy and implementation

tbd

[chiedo]

Would making this change mean we'd be breaking anchor links people already have bookmarked and if so, are we OK with that?

[chiedo]

What level of effort would it take to make sure all of the old anchor URL as of today will redirect to the new URLs based on the operation ID when we make this change?

@zeke / @sarahs

[zeke]

I think we could pretty easily add invisible companion anchors to continue supporting the old slugs.

[chiedo]

The obvious idea. Good thinking. Let's do both! So the old ones still work. But make the Operation ID URLs the default for anything that links to those sections.

[github-actions]

This issue is stale because it has been open 60 days with no activity.

[chiedo]

Still planning todo. Just taking time to get to it. Other priorities.

[chiedo]

@nschonni this one may be worth looking at if you decide to spend more time making improvements to the codebase!

[github-actions]

This issue is stale because it has been open 60 days with no activity.

[github-actions]

This issue is stale because it has been open 60 days with no activity.

[DiddiLeija]

Hi everybody! As I can see, this issue is not resolved. Can I work on it?

[heiskr]

I suspect it would be fine to simply switch to using the "summary key" as long as there are no duplicates on any page. I don't think we need to add "invisible companion anchors" for the current hashes, I'm concerned about added complexity and maintenance doing that. We would be happy to have an open source contributor help with this task, as we will likely not prioritize this internally.

[cmwilson21]

👋 Thanks all for the feedback in this issue. I spoke with the team and we are going to work on this internally. So I'm going to go ahead and close this issue.

Thanks again! 💛