关于application/vnd.github+json及自定义团队媒体类型的技术咨询

先聊聊application/vnd.github+json是什么 #

你猜的方向有点偏差，这个媒体类型其实和OpenAPI 3没有直接绑定，它是GitHub为自家REST API v3定义的自定义vendor媒体类型。

我们熟悉的application/json是通用JSON格式，但GitHub的API有大量专属业务逻辑和数据结构，所以他们用vnd.github+json给自家的JSON响应打了个「专属标签」：一方面和通用JSON格式做区分，另一方面标识这是贴合GitHub生态的定制化格式——比如部分接口指定这个Accept头时，会返回标准JSON里没有的元数据、仓库关联信息，甚至有些特定功能必须通过这个媒体类型才能触发。

简单说，它就是GitHub用来规范自家API请求/响应格式的专属标识，确保客户端能明确获取到符合GitHub业务逻辑的结构化数据。

如何为团队创建供外部调用的自定义媒体类型 #

如果要给新团队打造专属的自定义媒体类型，我建议按以下步骤落地：

• 遵循标准命名规范：按照IANA的官方规则，自定义媒体类型采用vnd.[组织/团队名].[自定义标识]+[基础格式]的结构。比如你们团队叫「TechFlow」，做任务管理API，基础格式是JSON，就可以命名为application/vnd.techflow.tasks+json；如果需要区分版本，还能加版本号，比如application/vnd.techflow.tasks.v2+json，后续迭代时不会破坏旧客户端的兼容性。
• 明确格式规则并文档化：把这个媒体类型对应的结构、字段含义、必填项、数据约束都梳理清楚。比如任务对象必须包含task_id、title，可选字段due_date的格式要求，status的可选值只能是todo/in_progress/done等。最好配上具体的请求、响应示例，让对接团队一眼就能看懂。
• 在API中实现支持：在你的API服务里处理请求头逻辑：当客户端在Accept头中指定你的自定义媒体类型时，返回符合规则的响应；如果是POST/PUT这类提交数据的请求，也要支持Content-Type设为该自定义类型，能正确解析对应的请求体。比如可以给个curl示例：

  curl -H "Accept: application/vnd.techflow.tasks+json" https://your-api.com/tasks/123
  

• 同步推广并对接沟通：把自定义媒体类型的适用场景、使用方法放到API文档的显眼位置，比如告诉其他团队：「当需要获取包含任务关联项目的完整数据时，请使用这个媒体类型」。也可以和对接团队做简短同步，避免误用。
• 预留兼容性迭代空间：后续如果要修改格式，不要直接改动现有媒体类型的规则，而是新增带版本号的新类型（比如从v1升级到v2），让旧版本客户端可以继续正常使用，保证平滑过渡。

内容的提问来源于stack exchange，提问作者Ayman Arif