SuperAPI AI 工具集

jsonapi

编程与开发

查看项目

更新于 10-16 04:35

技能介绍

用途:该技能聚焦 JSON:API v1.1 规范合规性,用于创建或修改 API 端点、审查 API 响应、验证 JSON:API 合规性。它只说明规范要求(MUST/MUST NOT),不提供具体实现代码模式;实现模式需配合 django-drf 技能,创建或修改端点时建议同时调用两者。

主要能力与规则:文档结构上,同一响应不得同时包含 data 与 errors,且至少包含 data、errors、meta 之一;资源对象必须使用 type 与 id(字符串),创建资源时不得包含 id;type 使用小写 kebab-case,id 与 type 不得放入 attributes,外键须用 relationships 表达。Content-Type 与 Accept 均须为 application/vnd.api+json,未加 ext/profile 时不得添加参数。关系须至少含 links、data、meta 之一,并使用资源链接格式 {"type": "...", "id": "..."}。错误须为数组 {"errors": [...]},status 为字符串,字段级错误须含 source.pointer。状态码方面,GET 成功 200、POST 201(须含 Location 头)、PATCH 200、DELETE 200/204,异步 202,冲突 409,未找到 404,禁止 403,错误请求 400,错误 Content-Type 返回 415。查询参数支持 page[number]/page[size]、filter[field]、sort(逗号分隔,- 表示降序)、fields[type]、include;不支持的参数、include 路径或排序字段须返回 400,指定 fields[type] 时不得返回额外字段。关系更新支持 to-one 的 PATCH 与置空 {"data": null},to-many 的 PATCH 替换、POST 添加、DELETE 移除。使用 include 时,included 中每个资源须可从主数据经关系链到达,不得含孤立或重复资源。

使用方式:实现或审查前,优先通过 Context7 MCP 查询最新规范,命令为 mcp_context7_resolve-library-id(query="jsonapi specification") 与 mcp_context7_query-docs(libraryId="<resolved-id>", query="[specific topic: relationships, errors, etc.]");若不可用,则用 WebFetch(url="https://jsonapi.org/format/", prompt="Extract rules for [specific topic]") 获取官方规范。

适用场景与限制:适用于需要严格遵循 JSON:API 的 API 设计与评审。资料未提供具体框架实现细节、测试方法或收费信息,实现与测试需参考 django-drf 与 prowler-test-api 技能。