Please use pull request to help to the translation
Version: 202310 Last Modify: 2023/10/10
-
All client requests will have 3 parameters uid, key and api in the QueryString, where uid is the user id. api is the API compatible version of the client, and the format is 6 digits, such as 202103. For different API versions, the client may have differences in return value processing and parameters. key is generated by main server to ensure the uid parameter has not been modified illegally. Private server could choose to verify the parameter, see example.
-
All return value types are json. When the return value is a list object, the same part of the returned structure is as follows:
{ "code": 0, "hasMore": true, "next": 0, "data": [] }Among them, hasMore indicates whether the list has more pages. next indicates the parameter of the next page, when the client requests the next page, the next value will be passed back to the server as from parameter.
- Key = 0
- Catch = 3
- Pad = 4
- Taiko = 5
- Ring = 6
- Slide = 7
- Live = 8
- Windows = 0
- MacOS = 1
- Tablet = 2
- iPhone = 3
- Android = 4
- iPad = 5
Purpose: The client send this request to server immediately after player enter the server host. The server host is not available until the request returns successful and the server API version is compatible with the client API version.
API: GET /api/store/info
Parameters none
Return structure
{
"code": 0,
"api": 202108,
"min": 202103,
"welcome": ""
}among them:
- api: Server API version
- min: The minimum client API version supported by the server
- welcome: welcome message, displayed after client verification, optional
Purpose: Get a list of charts under the specified query conditions
API: GET /api/store/list
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| word | string | Search keyword | Empty |
| org | int | Whether to return the original title | 0 |
| mode | int | returns the chart of the specified mode, see Mode Definition | -1 |
| lvge | int | returns the chart whose level is greater than this value | 0 |
| lvle | int | returns the chart whose level is less than this value | 0 |
| beta | int | Return to non-stable chart | 0 |
| from | int | paging start | 0 |
Return structure
{
"code": 0,
"hasMore": true,
"next": 0,
"data": [
{
"sid": 0,
"cover": "string",
"length": 0,
"bpm": 0,
"title": "string",
"artist": "string",
"mode": 0,
"time": 0
}
]
}among them:
- sid: song id, unique identifier
- cover: full cover url
- length: the length of the song, in seconds
- bpm: song bpm, float point
- mode: The bitmask value of the chart type included in the song. For example, the song contains both key and catch modes, and the bitmask value is (1 << 0) | (1 << 3) = 9
- time: Last update time of the song
Use: Get the chart currently being promoted, which will be displayed in the Promotion category of the client
API: GET /api/store/promote
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| org | int | Whether to return the original title | 0 |
| mode | int | returns the chart of the specified mode, see Mode Definition | -1 |
| from | int | paging start | 0 |
Return structure See the return structure of song list
Use: Get the chart currently updated by friends, which will be displayed in the Friends category of the client
API: GET /api/store/friend
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| org | int | Whether to return the original title | 0 |
| from | int | paging start | 0 |
Return structure See the return structure of song list
Purpose: Get all the charts under the specified song
API: GET /api/store/charts
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| sid | int | song id | required |
| beta | int | Return to non-stable chart | 0 |
| mode | int | returns the chart of the specified mode, see Mode Definition | -1 |
| from | int | paging start | 0 |
| promote | int | request from promotion list | 0 202206 added |
Return structure
{
"code": 0,
"hasMore": true,
"next": 0,
"data": [
{
"cid": 0,
"uid": 0,
"creator": "string",
"version": "string",
"level": 0,
"length": 0,
"type": 0,
"size": 0,
"mode": 0
}
]
}among them:
- cid: chart id
- uid: Author uid
- creator: Author username
- version: The difficulty name of the chart, such as 4K Easy
- level: the difficulty value of the chart
- length: the playing length of the chart, in seconds
- type: chart status, 2 for Stable, 1 for Beta, 0 for Alpha
- size: download size of chart, in bytes
- mode: Mode chart, for definition, please refer to Mode Definition
Use: Query the song with the specified id
API: GET /api/store/query
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| sid | int | song id | leave empty if cid is filled |
| cid | int | chart id | leave empty if sid is filled |
| org | int | Whether to return the original title | 0 |
Return structure The client will display the result in the song list, so although the result usually has only one item, it still reuses the return structure of the chart list.
Purpose: Get the download information of the specified chart
API: GET /api/store/download
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| cid | int | chart id | required |
Return structure
{
"code": 0,
"items": [
{
"name": "string",
"hash": "string",
"file": "string"
}
],
"sid": 0,
"cid": 0
}among them:
- code: return -2 when the corresponding chart of cid does not exist, and keep 0 in other cases
- items.name: file name
- items.hash: file md5 value
- items.file: The download url of the file
Use: Get a list of all activities
API: GET /api/store/events
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| active | int | returns the currently active events | 1 |
| from | int | paging start | 0 |
Return structure
{
"code": 0,
"hasMore": true,
"next": 0,
"data": [
{
"eid": 0,
"name": "string",
"sponsor":"string",
"start": "string",
"end": "string",
"active": true,
"cover": "string",
}
]
}among them:
- eid: event id
- name：event title
- sponsor：event sponsor, song list author, etc.
- start: the start time of the event, in the format yyyy-mm-dd
- end: the end time of the event, in the format yyyy-mm-dd
- cover: The cover url of the event
- active: Whether the event is active
Purpose: Get all the charts under the specified event
API: GET /api/store/event
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| eid | int | event id | required |
| org | int | Whether to return the original title | 0 |
| from | int | paging start | 0 |
Return structure
{
"code": 0,
"hasMore": true,
"next": 0,
"data": [
{
"sid": 0,
"cid": 0,
"uid": 0,
"creator": "string",
"title": "string",
"artist": "string",
"version": "string",
"level": 0,
"length": 0,
"type": 0,
"cover": "string",
"time": 0,
"mode": 0
}
]
}among them:
- cid: chart id
- uid: Author uid
- creator: Author username
- version: The difficulty name of the chart, such as 4K Easy
- level: difficulty value of the chart, number
- length: the playing length of the chart, in seconds
- type: chart status, 2 for Stable, 1 for Beta, 0 for Alpha
- mode: chart mode, for definition, please refer to Mode Definition
Malody server has two parts: main server and community host store server. The main server is hosted by official, provides ranking, communication and multiplayer for players around the world. In order to achieve this goal, the chart upload is divided into two parts:
- Chart information submission: the client requests to the main server to create a chart page, upload basic information, and get the chart id
- File upload: the client uses the chart id returned by the main server to request the Store server to upload the file
In this way, even if the player downloads the chart from multiple Store servers, as long as the md5 of the chart is the same, they will share the same ranking in main server.
In order to better balance the flexibility of uploading files and compatibility with upload APIs of different file storage providers, uploading a chart is divided into three steps:
- The client collects a list of all files that need to be uploaded, and requests the server to obtain the upload information, including upload target host, extra upload request data.
- According to the upload information, the client uploads the files to server in the form of multipart/form-data
- After all files are uploaded, the client collects the file information again, sends to the server, and confirms that the upload is complete
In step 2, mc files will be zipped, server receives zip files instead of plain mc files
Purpose: For to upload step 1
API: POST /api/store/upload/sign
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| sid | int | song id | required |
| cid | int | chart id | required |
| name | string | All file names, connected by commas | Empty |
| hash | string | All files md5, connected by comma | Empty |
Return structure
{
"code": 0,
"errorIndex": -1,
"errorMsg": "string",
"host": "string",
"meta": [
{
"post body key": "post body value"
}
]
}among them:
- errorIndex: When the server confirms there is a problem with the file to be uploaded, it returns the index of the file with the problem. The default is -1 means no error.
- errorMsg: text description of the reason for the error
- host: The upload target host address
- meta: key-value pairs of data that need to be added to form-data
Purpose: For to upload step 3
API: POST /api/store/upload/finish
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| sid | int | song id | required |
| cid | int | chart id | required |
| name | string | All file names, concatenated with a comma | Empty |
| hash | string | All files md5, connected by comma | Empty |
| size | int | total file size | 0 |
| main | string | md5 of the main chart file | Empty |
| title | string | song title | 202208 added |
| artit | string | song artist | 202208 added |
| orgt | string | title in original language | 202208 added |
| orga | string | artist in original language | 202208 added |
| version | string | chart version | 202208 added |
| mode | int | see Mode Definition | 202208 added |
| length | int | playable length | 202208 added |
| bpm | float | main bpm | 202208 added |
Return structure
{
"code": 0
}- code: -1 means name and hash are not equal in length after being split by comma. -2 means that the corresponding chart of cid does not exist.
Although the server should provides both upload and download services as documented here. But in fact, it is also possible to provide only download. That is, the chart of the server is obtained and saved by the server maintainer through his own methods. In this case, the sid and cid of the chart may not same as official records. and the official server will not be able to provide ranking service. But if chart has the same md5, the official server can still be able to find the correct official cid.
Purpose：To get available skins
API：GET /api/Skin/list
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| plat | int | Platform, see Platform definition | 0 |
| mode | int | returns the skin of the specified mode, see Mode Definition | -1 |
| word | string | search keyword | |
| from | int | paging start | 0 |
| v | int | version of client | 0 |
Return structure
{
"code": 0,
"hasMore": true,
"next": 0,
"data": [
{
"id": 0,
"uid": 0,
"creator": "string",
"name": "string",
"cover": "string",
"preview": "string",
"hot": 0,
"mode": 0,
"time": 0
}
]
}among them:
- uid：creator uid
- creator：creator name
- name：skin name
- cover: cover url of the skin
- preview：preview url of the skin, use | to separate multiple urls
- hot：hot counter/download counter
- time：update time, unix time
- mode：Mode chart, for definition, please refer to Mode Definition
Purpose：Get download url for skin
API：POST /api/skin/buy
Parameters
| Parameters | Type | Meaning | Default Value |
|---|---|---|---|
| uid | int | user id | |
| sid | int | skin id |
Return structure
{
"code": 0,
"data": {
"name": "string",
"url": "string",
"id": 0
}
}among them：
- code：-2 means that the corresponding skin of sid does not exist.
- name: skin file name
- url：download url
- id：skin id