app/flatpages/help/api.md

   1 title: API
   2
   3 ## Authentication
   4
   5 Not all endpoints require authentication.
   6 Authentication is done using Bearer tokens:
   7
   8         Authorization: Bearer YOURTOKEN
   9
  10 You can use the `/api/whoami` to check authentication.
  11
  12 ## Endpoints
  13
  14 ### Misc
  15
  16 * GET `/api/whoami/` - Json dictionary with the following keys:
  17         * `is_authenticated` - True on successful API authentication
  18         * `username` - Username of the user authenticated as, null otherwise.
  19         * 403 will be thrown on unsupported authentication type, invalid access token, or other errors.
  20
  21 ### Packages
  22
  23 * GET `/api/packages/` - See [Package Queries](#package-queries)
  24 * GET `/api/scores/` - See [Package Queries](#package-queries)
  25 * GET `/api/packages/<username>/<name>/`
  26
  27 ### Releases
  28
  29 * GET `/api/packages/<username>/<name>/releases/`
  30 * POST `/api/packages/<username>/<name>/releases/new/`
  31         * Requires authentication.
  32         * `title`: human-readable name of the release.
  33         * `method`: Release-creation method, only `git` is supported.
  34         * `min_protocol`: (Optional) minimum Minetest protocol version. See [Minetest](#minetest).
  35         * `min_protocol`: (Optional) maximum Minetest protocol version. See [Minetest](#minetest).
  36         * If `git` release-creation method:
  37                 * `ref` - git reference, eg: `master`.
  38
  39
  40 ### Topics
  41
  42 * GET `/api/topics/` - Supports [Package Queries](#package-queries), and the following two options:
  43     * `show_added` - Show topics which exist as packages, default true.
  44         * `show_discarded` - Show topics which have been marked as outdated, default false.
  45
  46 ### Minetest
  47
  48 * GET `/api/minetest_versions/`
  49
  50
  51 ## Package Queries
  52
  53 Example:
  54
  55         /api/packages/?type=mod&type=game&q=mobs+fun&hide=nonfree&hide=gore
  56
  57 Supported query parameters:
  58
  59 * `type` - Package types (`mod`, `game`, `txp`).
  60 * `q` - Query string
  61 * `random` - When present, enable random ordering and ignore `sort`.
  62 * `hide` - Hide content based on [Content Flags](content_flags).
  63 * `sort` - Sort by (`name`, `views`, `date`, `score`).
  64 * `order` - Sort ascending (`Asc`) or descending (`desc`).
  65 * `protocol_version` - Only show packages supported by this Minetest protocol version.