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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user