contentdb/api.md at 5d32d7922f1977d0ee3d0d9c4655f563f517a24d

mirror of https://github.com/minetest/contentdb.git synced 2024-11-10 09:33:44 +01:00

rubenwardy 5d32d7922f Add Maintenance State field

Fixes #160

2021-12-20 21:07:12 +00:00

12 KiB

Raw Blame History

title: API

Resources

How the Minetest client uses the API

Responses and Error Handling

If there is an error, the response will be JSON similar to the following with a non-200 status code:

{
    "success": false,
    "error": "The error message"
}

Successful GET requests will return the resource's information directly as a JSON response.

Other successful results will return a dictionary with success equaling true, and often other keys with information. For example:

{
    "success": true,
    "release": {
        /* same as returned by a GET */ 
    }
}

Authentication

Not all endpoints require authentication, but it is done using Bearer tokens:

curl https://content.minetest.net/api/whoami/ \
    -H "Authorization: Bearer YOURTOKEN"

Tokens can be attained by visiting Settings > API Tokens.

GET /api/whoami/: JSON dictionary with the following keys:
- is_authenticated: True on successful API authentication
- username: Username of the user authenticated as, null otherwise.
- 4xx status codes will be thrown on unsupported authentication type, invalid access token, or other errors.

Packages

GET /api/packages/ (List)
- See Package Queries
GET /api/packages/<username>/<name>/ (Read)
PUT /api/packages/<author>/<name>/ (Update)
- Requires authentication.
- JSON dictionary with any of these keys (all are optional, null to delete Nullables):
  - type: One of GAME, MOD, TXP.
  - title: Human-readable title.
  - name: Technical name (needs permission if already approved).
  - short_description
  - dev_state: One of WIP, BETA, ACTIVELY_DEVELOPED, MAINTENANCE_ONLY, AS_IS, DEPRECATED, LOOKING_FOR_MAINTAINER.
  - tags: List of tag names.
  - content_warnings: List of content warning names.
  - license: A license name.
  - media_license: A license name.
  - long_description: Long markdown description.
  - repo: Git repo URL.
  - website: Website URL.
  - issue_tracker: Issue tracker URL.
  - forums: forum topic ID.
GET /api/packages/<username>/<name>/dependencies/
- If query argument only_hard is present, only hard deps will be returned.

You can download a package by building one of the two URLs:

https://content.minetest.net/packages/${author}/${name}/download/`
https://content.minetest.net/packages/${author}/${name}/releases/${release}/download/`

Examples:

# Edit package
curl -X PUT https://content.minetest.net/api/packages/username/name/ \
    -H "Authorization: Bearer YOURTOKEN" -H "Content-Type: application/json" \
    -d '{ "title": "Foo bar", "tags": ["pvp", "survival"], "license": "MIT" }'
    
# Remove website URL
curl -X PUT https://content.minetest.net/api/packages/username/name/ \
    -H "Authorization: Bearer YOURTOKEN" -H "Content-Type: application/json" \
    -d '{ "website": null }'

Package Queries

Example:

/api/packages/?type=mod&type=game&q=mobs+fun&hide=nonfree&hide=gore

Supported query parameters:

type: Package types (mod, game, txp).
q: Query string.
author: Filter by author.
tag: Filter by tags.
random: When present, enable random ordering and ignore sort.
limit: Return at most limit packages.
hide: Hide content based on Content Flags.
sort: Sort by (name, title, score, reviews, downloads, created_at, approved_at, last_release).
order: Sort ascending (asc) or descending (desc).
protocol_version: Only show packages supported by this Minetest protocol version.
engine_version: Only show packages supported by this Minetest engine version, eg: 5.3.0.
fmt: How the response is formated.
- keys: author/name only.
- short: stuff needed for the Minetest client.

Releases

GET /api/releases/ (List)
- Limited to 30 most recent releases.
- Optional arguments:
  - author: Filter by author
  - maintainer: Filter by maintainer
- Returns array of release dictionaries with keys:
  - id: release ID
  - title: human-readable title
  - release_date: Date released
  - url: download URL
  - commit: commit hash or null
  - downloads: number of downloads
  - min_minetest_version: dict or null, minimum supported minetest version (inclusive).
  - max_minetest_version: dict or null, minimum supported minetest version (inclusive).
  - package
    - author: author username
    - name: technical name
    - type: mod, game, or txp
GET /api/packages/<username>/<name>/releases/ (List)
- Returns array of release dictionaries, see above, but without package info.
GET /api/packages/<username>/<name>/releases/<id>/ (Read)
POST /api/packages/<username>/<name>/releases/new/ (Create)
- Requires authentication.
- Body can be JSON or multipart form data. Zip uploads must be multipart form data.
- title: human-readable name of the release.
- For Git release creation:
  - method: must be git.
  - ref: (Optional) git reference, eg: master.
- For zip upload release creation:
  - file: multipart file to upload, like <input type="file" name="file">.
  - commit: (Optional) Source Git commit hash, for informational purposes.
- You can set min and max Minetest Versions using the content's .conf file.
DELETE /api/packages/<username>/<name>/releases/<id>/ (Delete)
- Requires authentication.
- Deletes release.

Examples:

# Create release from Git
curl -X POST https://content.minetest.net/api/packages/username/name/releases/new/ \
    -H "Authorization: Bearer YOURTOKEN" -H "Content-Type: application/json" \
    -d '{ "method": "git", "title": "My Release", "ref": "master" }'

# Create release from zip upload
curl -X POST https://content.minetest.net/api/packages/username/name/releases/new/ \
    -H "Authorization: Bearer YOURTOKEN" \
    -F title="My Release" -F file=@path/to/file.zip

# Create release from zip upload with commit hash
curl -X POST https://content.minetest.net/api/packages/username/name/releases/new/ \
    -H "Authorization: Bearer YOURTOKEN" \
    -F title="My Release" -F commit="8ef74deec170a8ce789f6055a59d43876d16a7ea" -F file=@path/to/file.zip

# Delete release
curl -X DELETE https://content.minetest.net/api/packages/username/name/releases/3/ \
    -H "Authorization: Bearer YOURTOKEN"

Screenshots

GET /api/packages/<username>/<name>/screenshots/ (List)
- Returns array of screenshot dictionaries with keys:
  - id: screenshot ID
  - approved: true if approved and visible.
  - title: human-readable name for the screenshot, shown as a caption and alt text.
  - url: absolute URL to screenshot.
  - created_at: ISO time.
  - order: Number used in ordering.
GET /api/packages/<username>/<name>/screenshots/<id>/ (Read)
- Returns screenshot dictionary like above.
POST /api/packages/<username>/<name>/screenshots/new/ (Create)
- Requires authentication.
- Body is multipart form data.
- title: human-readable name for the screenshot, shown as a caption and alt text.
- file: multipart file to upload, like <input type=file>.
DELETE /api/packages/<username>/<name>/screenshots/<id>/ (Delete)
- Requires authentication.
- Deletes screenshot.
POST /api/packages/<username>/<name>/screenshots/order/
- Requires authentication.
- Body is a JSON array containing the screenshot IDs in their order.

Currently, to get a different size of thumbnail you can replace the number in /thumbnails/1/ with any number from 1-3. The resolutions returned may change in the future, and we may move to a more capable thumbnail generation.

Examples:

# Create screenshot
curl -X POST https://content.minetest.net/api/packages/username/name/screenshots/new/ \
    -H "Authorization: Bearer YOURTOKEN" \
    -F title="My Release" -F file=@path/to/screnshot.png

# Delete screenshot
curl -X DELETE https://content.minetest.net/api/packages/username/name/screenshots/3/ \
    -H "Authorization: Bearer YOURTOKEN" 
    
# Reorder screenshots
curl -X POST https://content.minetest.net/api/packages/username/name/screenshots/order/ \
    -H "Authorization: Bearer YOURTOKEN" -H "Content-Type: application/json" \
    -d "[13, 2, 5, 7]"

Reviews

GET /api/packages/<username>/<name>/reviews/ (List)
- Returns array of review dictionaries with keys:
  - user: dictionary with display_name and username.
  - title: review title
  - comment: the text
  - is_positive: boolean
  - created_at: iso timestamp
  - votes: dictionary with helpful and unhelpful,
GET /api/reviews/ (List)
- Returns a paginated response. This is a dictionary with page, url, and items.
  - page: page number, integer from 1 to max
  - per_page: number of items per page, same as n
  - page_count: number of pages
  - total: total number of results
  - urls: dictionary containing
    - next: url to next page
    - previous: url to previous page
  - items: array of review dictionaries, like above
    - Each review also has a package dictionary with type, author and name
- Query arguments:
  - page: page number, integer from 1 to max
  - n: number of results per page, max 100
  - author: filter by review author username
  - is_positive: true or false. Default: null
  - q: filter by title (case insensitive, no fulltext search)

Example:

[
  {
    "comment": "This is a really good mod!", 
    "created_at": "2021-11-24T16:18:33.764084", 
    "is_positive": true, 
    "title": "Really good", 
    "user": {
      "display_name": "rubenwardy", 
      "username": "rubenwardy"
    }, 
    "votes": {
      "helpful": 0, 
      "unhelpful": 0
    }
  }
]

Topics

GET /api/topics/ (View)
- See Topic Queries

Topic Queries

Example:

/api/topics/?q=mobs&type=mod&type=game

Supported query parameters:

q: Query string.
type: Package types (mod, game, txp).
sort: Sort by (name, views, created_at).
show_added: Show topics that have an existing package.
show_discarded: Show topics marked as discarded.
limit: Return at most limit topics.

Types

Content Warnings

GET /api/content_warnings/ (View): List of:
- name: technical name
- title: human-readable title
- description: tag description or null

Licenses

GET /api/licenses/ (View): List of:
- name
- is_foss: whether the license is foss

Minetest Versions

GET /api/minetest_versions/ (View)
- name: Version name.
- is_dev: boolean, is dev version.
- protocol_version: protocol version umber.

Misc

GET /api/scores/ (View)
- See Top Packages Algorithm.
- Supports Package Queries.
- Returns list of:
  - author: package author name.
  - name: package technical name.
  - downloads: number of downloads.
  - score: total package score.
  - score_reviews: score from reviews.
  - score_downloads: score from downloads.
GET /api/homepage/ (View) - get contents of homepage.
- count: number of packages
- downloads: get number of downloads
- new: new packages
- updated: recently updated packages
- pop_mod: popular mods
- pop_txp: popular textures
- pop_game: popular games
- high_reviewed: highest reviewed

12 KiB Raw Blame History

Resources

Responses and Error Handling

Authentication

Packages

Package Queries

Releases

Screenshots

Reviews

Topics

Topic Queries

Types

Tags

Content Warnings

Licenses

Minetest Versions

Misc

12 KiB

Raw Blame History