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 Tokens can be attained by visiting [Profile > "API Tokens"](/user/tokens/).
  13
  14 ## Endpoints
  15
  16 ### Misc
  17
  18 * GET `/api/whoami/` - Json dictionary with the following keys:
  19         * `is_authenticated` - True on successful API authentication
  20         * `username` - Username of the user authenticated as, null otherwise.
  21         * 4xx status codes will be thrown on unsupported authentication type, invalid access token, or other errors.
  22
  23 ### Packages
  24
  25 * GET `/api/packages/` - See [Package Queries](#package-queries)
  26 * GET `/api/scores/` - See [Package Queries](#package-queries)
  27 * GET `/api/packages/<username>/<name>/`
  28 * GET `/api/packages/<username>/<name>/dependencies/`
  29     * If query argument `only_hard` is present, only hard deps will be returned.
  30
  31 ### Releases
  32
  33 * GET `/api/packages/<username>/<name>/releases/`
  34 * POST `/api/packages/<username>/<name>/releases/new/`
  35         * Requires authentication.
  36         * `title`: human-readable name of the release.
  37         * `method`: Release-creation method, only `git` is supported.
  38         * If `git` release-creation method:
  39                 * `ref` - git reference, eg: `master`.
  40         * You can set min and max Minetest Versions [using the content's .conf file](/help/package_config/).
  41
  42
  43 ### Topics
  44
  45 * GET `/api/topics/` - Supports [Package Queries](#package-queries), and the following two options:
  46         * `show_added` - Show topics which exist as packages, default true.
  47         * `show_discarded` - Show topics which have been marked as outdated, default false.
  48
  49 ### Minetest
  50
  51 * GET `/api/minetest_versions/`
  52
  53
  54 ## Package Queries
  55
  56 Example:
  57
  58         /api/packages/?type=mod&type=game&q=mobs+fun&hide=nonfree&hide=gore
  59
  60 Supported query parameters:
  61
  62 * `type` - Package types (`mod`, `game`, `txp`).
  63 * `q` - Query string.
  64 * `author` - Filter by author.
  65 * `tag` - Filter by tags.
  66 * `random` - When present, enable random ordering and ignore `sort`.
  67 * `limit` - Return at most `limit` packages.
  68 * `hide` - Hide content based on [Content Flags](/help/content_flags/).
  69 * `sort` - Sort by (`name`, `title`, `score`, `downloads`, `created_at`, `last_release`).
  70 * `order` - Sort ascending (`asc`) or descending (`desc`).
  71 * `protocol_version` - Only show packages supported by this Minetest protocol version.
  72 * `engine_version` - Only show packages supported by this Minetest engine version, eg: `5.3.0`.
  73
  74
  75 ## Topic Queries
  76
  77 Example:
  78
  79         /api/topics/?q=mobs
  80
  81 Supported query parameters:
  82
  83 * `q` - Query string.
  84 * `sort` - Sort by (`name`, `views`, `date`).
  85 * `order` - Sort ascending (`asc`) or descending (`desc`).
  86 * `show_added` - Show topics that have an existing package.
  87 * `show_discarded` - Show topics marked as discarded.
  88 * `limit` - Return at most `limit` topics.