265 lines
9.0 KiB
Markdown
265 lines
9.0 KiB
Markdown
# Get Project
|
||
|
||
获取 Modrinth 上的单个或多个 project 的基本数据。
|
||
|
||
---
|
||
|
||
## GET `/project/{id|slug}`
|
||
|
||
获取单个 project 的完整信息。
|
||
|
||
### 路径参数
|
||
|
||
| 参数 | 位置 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `id\|slug` | path | `string` | ✅ | Project 的 ID（base62 编码）或 slug（用于自定义 URL）。 |
|
||
|
||
### 响应 `200 OK`
|
||
|
||
返回 [`Project`](#project-模型) 对象。
|
||
|
||
### 响应 `404 Not Found`
|
||
|
||
指定的 project 不存在或无权限访问。
|
||
|
||
---
|
||
|
||
## GET `/projects`
|
||
|
||
批量获取多个 project 的完整信息。
|
||
|
||
### 查询参数
|
||
|
||
| 参数 | 位置 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `ids` | query | `string` | ✅ | 以 JSON 数组格式指定要获取的 project ID 或 slug。例如 `["AABBCCDD", "my_project"]`。 |
|
||
|
||
### 响应 `200 OK`
|
||
|
||
返回 [`Project`](#project-模型) 对象数组。
|
||
|
||
---
|
||
|
||
## Project 模型
|
||
|
||
`Project` 继承自多个层级 schema，完整字段如下。
|
||
|
||
> **🔗 Schema 继承关系:** `Project` = `NonSearchProject` + `ServerRenderedProject` + 自身字段
|
||
>
|
||
> 其中 `NonSearchProject` 和 `ServerRenderedProject` 均继承自 `BaseProject`。
|
||
|
||
```
|
||
|
||
Project
|
||
├── BaseProject (基础信息)
|
||
│ ├── slug
|
||
│ ├── title
|
||
│ ├── description
|
||
│ ├── categories
|
||
│ ├── client_side
|
||
│ └── server_side
|
||
├── NonSearchProject (非搜索专属字段)
|
||
│ ├── body
|
||
│ ├── status
|
||
│ ├── requested_status
|
||
│ ├── additional_categories
|
||
│ ├── issues_url
|
||
│ ├── source_url
|
||
│ ├── wiki_url
|
||
│ ├── discord_url
|
||
│ └── donation_urls
|
||
├── ServerRenderedProject (服务端渲染字段)
|
||
│ ├── project_type
|
||
│ ├── downloads
|
||
│ ├── icon_url
|
||
│ ├── color
|
||
│ ├── thread_id
|
||
│ └── monetization_status
|
||
└── Project (自身字段)
|
||
├── id
|
||
├── team
|
||
├── body_url ⚠️
|
||
├── moderator_message ⚠️
|
||
├── published
|
||
├── updated
|
||
├── approved
|
||
├── queued
|
||
├── followers
|
||
├── license
|
||
├── versions
|
||
├── game_versions
|
||
├── loaders
|
||
└── gallery
|
||
|
||
```
|
||
|
||
### 字段一览
|
||
|
||
| 字段 | 类型 | 来源 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | `string` | Project | Project ID（base62 编码）。 |
|
||
| `slug` | `string` | BaseProject | 用于自定义 URL 的简短标识符，正则 `^[\w!@$().`+,"'-]{3,64}$`。 |
|
||
| `title` | `string` | BaseProject | Project 名称或标题。 |
|
||
| `description` | `string` | BaseProject | 简短描述。 |
|
||
| `body` | `string` | NonSearchProject | 长描述（支持 Markdown）。 |
|
||
| `categories` | `string[]` | BaseProject | 主分类列表。 |
|
||
| `additional_categories` | `string[]` | NonSearchProject | 附加分类（可搜索但非主要）。 |
|
||
| `client_side` | `string` | BaseProject | 客户端支持类型。`required` / `optional` / `unsupported` / `unknown`。 |
|
||
| `server_side` | `string` | BaseProject | 服务端支持类型。`required` / `optional` / `unsupported` / `unknown`。 |
|
||
| `project_type` | `string` | ServerRenderedProject | 项目类型。`mod` / `modpack` / `resourcepack` / `shader`。 |
|
||
| `downloads` | `integer` | ServerRenderedProject | 总下载次数。 |
|
||
| `followers` | `integer` | Project | 关注者数量。 |
|
||
| `status` | `string` | NonSearchProject | 项目状态：`approved` / `archived` / `rejected` / `draft` / `unlisted` / `processing` / `withheld` / `scheduled` / `private` / `unknown`。 |
|
||
| `requested_status` | `string` ⚠️ | NonSearchProject | 申请中的状态。`approved` / `archived` / `unlisted` / `private` / `draft`。可为 `null`。 |
|
||
| `license` | [`ProjectLicense`](#projectlicense) | Project | 许可证信息。 |
|
||
| `team` | `string` | Project | 拥有此 project 的团队 ID。 |
|
||
| `published` | `string` (ISO-8601) | Project | 发布日期。 |
|
||
| `updated` | `string` (ISO-8601) | Project | 最后更新日期。 |
|
||
| `approved` | `string` (ISO-8601) ⚠️ | Project | 审核通过日期。可为 `null`。 |
|
||
| `queued` | `string` (ISO-8601) ⚠️ | Project | 提交审核日期。可为 `null`。 |
|
||
| `icon_url` | `string` ⚠️ | ServerRenderedProject | 图标 URL。可为 `null`。 |
|
||
| `color` | `integer` ⚠️ | ServerRenderedProject | 从图标自动生成的 RGB 颜色值。可为 `null`。 |
|
||
| `thread_id` | `string` | ServerRenderedProject | 关联的审核线程 ID。 |
|
||
| `monetization_status` | `string` | ServerRenderedProject | 变现状态。`monetized` / `demonetized` / `force-demonetized`。 |
|
||
| `issues_url` | `string` ⚠️ | NonSearchProject | 问题跟踪链接。可为 `null`。 |
|
||
| `source_url` | `string` ⚠️ | NonSearchProject | 源代码链接。可为 `null`。 |
|
||
| `wiki_url` | `string` ⚠️ | NonSearchProject | Wiki 链接。可为 `null`。 |
|
||
| `discord_url` | `string` ⚠️ | NonSearchProject | Discord 邀请链接。可为 `null`。 |
|
||
| `donation_urls` | [`ProjectDonationURL[]`](#projectdonationurl) | NonSearchProject | 捐赠链接列表。 |
|
||
| `body_url` | `string` ⚠️ ⛔ | Project | 已弃用，始终为 `null`。 |
|
||
| `moderator_message` | [`ModeratorMessage`](#moderatormessage) ⛔ | Project | 已弃用，始终为 `null`。 |
|
||
| `versions` | `string[]` | Project | 所有版本 ID 列表（`draft` 状态时为空）。 |
|
||
| `game_versions` | `string[]` | Project | 支持的 Minecraft 版本列表。 |
|
||
| `loaders` | `string[]` | Project | 支持的模组加载器列表。 |
|
||
| `gallery` | [`GalleryImage[]`](#galleryimage) | Project | 图库图片列表。 |
|
||
|
||
> ⚠️ 表示可为 `null`。⛔ 表示已弃用。
|
||
|
||
---
|
||
|
||
### ProjectLicense
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | `string` | SPDX 许可证 ID（如 `LGPL-3.0-or-later`）。 |
|
||
| `name` | `string` | 许可证全名（如 `GNU Lesser General Public License v3 or later`）。 |
|
||
| `url` | `string` ⚠️ | 许可证文本 URL，可为 `null`。 |
|
||
|
||
### ProjectDonationURL
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | `string` | 捐赠平台 ID（如 `patreon`）。 |
|
||
| `platform` | `string` | 捐赠平台名称（如 `Patreon`）。 |
|
||
| `url` | `string` | 捐赠链接。 |
|
||
|
||
### GalleryImage
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `url` | `string` | 图片 URL。 |
|
||
| `featured` | `boolean` | 是否为精选图片。 |
|
||
| `title` | `string` ⚠️ | 图片标题，可为 `null`。 |
|
||
| `description` | `string` ⚠️ | 图片描述，可为 `null`。 |
|
||
| `created` | `string` (ISO-8601) | 创建日期。 |
|
||
| `ordering` | `integer` | 排序序号（先按此字段排，再按标题字母序排）。 |
|
||
|
||
### ModeratorMessage
|
||
|
||
> ⛔ 已弃用，始终为 `null`。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `message` | `string` | 审核员留言。 |
|
||
| `body` | `string` ⚠️ | 留言详细内容，可为 `null`。 |
|
||
|
||
---
|
||
|
||
## 示例
|
||
|
||
### 请求 - 获取单个 project
|
||
|
||
```bash
|
||
curl -X GET "https://api.modrinth.com/v2/project/my_project"
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"id": "AABBCCDD",
|
||
"slug": "my_project",
|
||
"team": "MMNNOOPP",
|
||
"title": "My Project",
|
||
"description": "A short description",
|
||
"body": "A long body describing my project in detail",
|
||
"categories": ["technology", "adventure", "fabric"],
|
||
"additional_categories": ["utility"],
|
||
"client_side": "required",
|
||
"server_side": "optional",
|
||
"project_type": "mod",
|
||
"status": "approved",
|
||
"requested_status": null,
|
||
"downloads": 52341,
|
||
"followers": 1203,
|
||
"license": {
|
||
"id": "MIT",
|
||
"name": "MIT License",
|
||
"url": "https://opensource.org/licenses/MIT"
|
||
},
|
||
"published": "2023-03-15T10:30:00Z",
|
||
"updated": "2024-01-20T14:22:00Z",
|
||
"approved": "2023-03-15T12:00:00Z",
|
||
"queued": null,
|
||
"icon_url": "https://cdn.modrinth.com/data/AABBCCDD/icon.png",
|
||
"color": 8703084,
|
||
"thread_id": "TTUUVVWW",
|
||
"monetization_status": "monetized",
|
||
"issues_url": "https://github.com/my_user/my_project/issues",
|
||
"source_url": "https://github.com/my_user/my_project",
|
||
"wiki_url": null,
|
||
"discord_url": "https://discord.gg/AaBbCcDd",
|
||
"donation_urls": [
|
||
{
|
||
"id": "patreon",
|
||
"platform": "Patreon",
|
||
"url": "https://www.patreon.com/my_user"
|
||
}
|
||
],
|
||
"body_url": null,
|
||
"moderator_message": null,
|
||
"versions": ["IIJJKKLL", "QaRSSTT"],
|
||
"game_versions": ["1.19", "1.19.1", "1.19.2", "1.19.3"],
|
||
"loaders": ["forge", "fabric", "quilt"],
|
||
"gallery": [
|
||
{
|
||
"url": "https://cdn.modrinth.com/data/AABBCCDD/images/009b7d8d6e8bf04968a29421117c59b3efe2351a.png",
|
||
"featured": true,
|
||
"title": "My awesome screenshot!",
|
||
"description": "This awesome screenshot shows all of the blocks in my mod!",
|
||
"created": "2023-06-01T08:15:00Z",
|
||
"ordering": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 请求 - 批量获取多个 project
|
||
|
||
```bash
|
||
curl -X GET "https://api.modrinth.com/v2/projects?ids=%5B%22AABBCCDD%22%2C%22my_project%22%5D"
|
||
```
|
||
|
||
> URL 编码后的 `ids` 参数值为 `["AABBCCDD","my_project"]`。
|
||
|
||
### 响应
|
||
|
||
```json
|
||
[
|
||
{ "...": "..." },
|
||
{ "...": "..." }
|
||
]
|
||
```
|
||
|
||
返回 `Project` 对象数组，每个对象结构与单个获取一致。
|