1
0
mirror of synced 2025-12-23 03:44:00 -05:00

Recommend an Accept header without V3 in it when documenting our REST API operations (#28477)

* Recommend an `Accept` header for REST API requests which doesn't mention V3

In the documentation for every REST API, in the "Headers"
section, we say for the `Accept` header that:

> Setting to `application/vnd.github.v3+json` is recommended.

Putting the V3 bit in doesn't actually do anything - in fact,
a high proportion of API consumers don't do it - and this
recommendation is going to be confusing once we launch our
new API versioning. This recommends that people use
`application/vnd.gitrhub+json` instead.

We could just recommend `application/json` - I'd be in favour
of that! - but I'm trying to make this change as small as
possible.

* Update cURL and GitHub CLI code examples to use an `Accept` header without V3

Co-authored-by: Sarah Edwards <skedwards88@github.com>
This commit is contained in:
Tim Rogers
2022-06-29 16:50:07 +01:00
committed by GitHub
parent 149246361f
commit 037d6328b8
2 changed files with 5 additions and 5 deletions

View File

@@ -9,7 +9,7 @@ import type { CodeSample, Operation } from '../rest/types'
For example:
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Accept: application/vnd.github+json" \
https://{hostname}/api/v3/repos/OWNER/REPO/deployments \
-d '{"ref":"topic-branch","payload":"{ \"deploy\": \"migrate\" }","description":"Deploy request from hubot"}'
*/
@@ -17,7 +17,7 @@ export function getShellExample(operation: Operation, codeSample: CodeSample) {
// This allows us to display custom media types like application/sarif+json
const defaultAcceptHeader = codeSample?.response?.contentType?.includes('+json')
? codeSample.response.contentType
: 'application/vnd.github.v3+json'
: 'application/vnd.github+json'
const requestPath = codeSample?.request?.parameters
? parseTemplate(operation.requestPath).expand(codeSample.request.parameters)
@@ -55,14 +55,14 @@ export function getShellExample(operation: Operation, codeSample: CodeSample) {
For example:
gh api \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Accept: application/vnd.github+json" \
/repos/OWNER/REPO/deployments \
-fref,topic-branch=0,payload,{ "deploy": "migrate" }=1,description,Deploy request from hubot=2
*/
export function getGHExample(operation: Operation, codeSample: CodeSample) {
const defaultAcceptHeader = codeSample?.response?.contentType?.includes('+json')
? codeSample.response.contentType
: 'application/vnd.github.v3+json'
: 'application/vnd.github+json'
const hostname = operation.serverUrl !== 'https://api.github.com' ? '--hostname HOSTNAME' : ''
const requestPath = codeSample?.request?.parameters