contentdb/app/flatpages/help/api.md

69 lines
2.2 KiB
Markdown
Raw Normal View History

2019-11-22 15:33:22 +01:00
title: API
## Authentication
Not all endpoints require authentication.
Authentication is done using Bearer tokens:
Authorization: Bearer YOURTOKEN
You can use the `/api/whoami` to check authentication.
2020-06-03 19:22:23 +02:00
Tokens can be attained by visiting [Profile > "API Tokens"](/user/tokens/).
2019-11-22 15:33:22 +01:00
## Endpoints
### Misc
* 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.
2019-11-22 15:33:22 +01:00
### Packages
* GET `/api/packages/` - See [Package Queries](#package-queries)
2020-04-21 19:15:13 +02:00
* GET `/api/scores/` - See [Package Queries](#package-queries)
2019-11-22 15:33:22 +01:00
* GET `/api/packages/<username>/<name>/`
2020-06-05 05:48:53 +02:00
* GET `/api/packages/<username>/<name>/dependencies/`
2020-06-05 05:46:46 +02:00
* If query argument `only_hard` is present, only hard deps will be returned.
2019-11-22 15:33:22 +01:00
2020-01-24 21:21:40 +01:00
### Releases
* GET `/api/packages/<username>/<name>/releases/`
* POST `/api/packages/<username>/<name>/releases/new/`
2020-01-24 21:21:40 +01:00
* Requires authentication.
* `title`: human-readable name of the release.
* `method`: Release-creation method, only `git` is supported.
* If `git` release-creation method:
* `ref` - git reference, eg: `master`.
2020-06-03 19:22:23 +02:00
* You can set min and max Minetest Versions [using the content's .conf file](/help/package_config/).
2020-01-24 21:21:40 +01:00
2019-11-22 15:33:22 +01:00
### Topics
* GET `/api/topics/` - Supports [Package Queries](#package-queries), and the following two options:
2020-06-03 19:22:23 +02:00
* `show_added` - Show topics which exist as packages, default true.
2019-11-22 15:33:22 +01:00
* `show_discarded` - Show topics which have been marked as outdated, default false.
### Minetest
* GET `/api/minetest_versions/`
## 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
* `random` - When present, enable random ordering and ignore `sort`.
* `hide` - Hide content based on [Content Flags](/help/content_flags/).
2019-11-22 15:33:22 +01:00
* `sort` - Sort by (`name`, `views`, `date`, `score`).
* `order` - Sort ascending (`Asc`) or descending (`desc`).
* `protocol_version` - Only show packages supported by this Minetest protocol version.