aurweb/doc/api.md

aurweb v6 /api

Specification for version 6 of the metadata REST-API

Endpoints

Endpoints are classified in 3 categories:

• Search -> Search for packages
• Info -> Lookup information for package (exact keyword)
• Suggest -> Search for package names (max. 20 results)

Search

Performs a search query according to the by parameter.

• GET/api/v6/search/{arg} GET/api/v6/search/{by}/{arg} GET/api/v6/search/{by}/{mode}/{arg}
  • arg _{(path; mandatory)}
  • by _{(path; optional)}
  • mode _{(path; optional)}

Parameters

• by

  The field that is utilized in the search query If not specified, searching is performend with name-desc

  • Type: string
  • Allowed values
    • name
    • name-desc
  • Default: name-desc

• mode

  The search-mode that is being used to query packages If not specified, searching is performend with contains

  • Type: string
  • Allowed values
    • contains
    • starts-with
  • Default: contains

• arg

  The argument/search-term(s) for the search query Multiple terms/words can be supplied (space separated) to perform and AND-like query

  • Type: string

Response

Data is returned in JSON format. Empty fields are ommitted in the output.

200 - OK

• PackageData

  {
      "resultcount": 1,
      "results": [
          {
              "Name": "my-pkg",
              "Description": "Package description",
              "Version": "1.7.5-1",
              "PackageBase": "my-pkg",
              "URL": "https://example.com",
              "URLPath": "/cgit/aur.git/snapshot/my-pkg.tar.gz",
              "Maintainer": "someone",
              "Submitter": "someone",
              "FirstSubmitted": 1648375227,
              "LastModified": 1666386881,
              "OutOfDate": 1648375227,
              "NumVotes": 10,
              "Popularity": 6.463867,
              "License": [
                  "MIT",
                  "GPL3"
              ],
              "Depends": [
                  "some-pkg",
                  "another-pkg"
              ],
              "MakeDepends": [
                  "some-pkg",
                  "another-pkg"
              ],
              "OptDepends": [
                  "some-pkg",
                  "another-pkg"
              ],
              "CheckDepends": [
                  "some-pkg",
                  "another-pkg"
              ],
              "Provides": [
                  "some-pkg",
                  "another-pkg"
              ],
              "Conflicts": [
                  "some-pkg",
                  "another-pkg"
              ],
              "Replaces": [
                  "some-pkg",
                  "another-pkg"
              ],
              "Groups": [
                  "some-grp",
                  "another-grp"
              ],
              "Keywords": [
                  "some-keyword",
                  "another-keyword"
              ],
              "CoMaintainers": [
                  "someone",
                  "another-one"
              ]
          }
      ],
      "type": "search",
      "version": 6
  }
  

400 - Bad Request

• Error

  {
      "error": "Incorrect by field specified",
      "resultcount": 1,
      "results": [],
      "type": "error",
      "version": 6
  }
  

Info

Returns a list of detailed package data for one or more packages

Single lookup

• GET/api/v6/info/{arg} GET/api/v6/info/{by}/{arg}
  • arg _{(path; mandatory)}
  • by _{(path; optional)}

Multi lookup

• GET/api/v6/info?arg=xyz&arg=abc GET/api/v6/info?by=provides&arg=xyz&arg=abc

  • arg _{(query-string; mandatory; one or more)}
  • by _{(query-string; optional)}

• POST/api/v6/info

  • BODY (application/x-www-form-urlencoded):

    arg=one&arg=two&by=provides
    

Parameters

• by

  The field is being utilized in the lookup query If not specified, a lookup is performend with name

  • Type: string
  • Allowed values
    • name
    • depends
    • checkdepends
    • optdepends
    • makedepends
    • maintainer
    • submitter
    • provides
    • conflicts
    • replaces
    • keywords
    • groups
    • comaintainers
  • Default: name

• arg

  One or more keywords

  • Type: string or string-array (depending on the endpoint)

Response

Data is returned in JSON format. Empty fields are ommitted in the output.

200 - OK

• PackageData

  See Search type

400 - Bad Request

• Error

  See Search type

Suggest

Returns a list of package names starting with the supplied argument. Mostly used for auto-completion fields when typing.

Starts-with search

• GET/api/v6/suggest/{arg}

  • arg _{(path; mandatory)}

• GET/api/v6/suggest-pkgbase/{arg}

  • arg _{(path; mandatory)}

Response

Data is returned in JSON format.

200 - OK

• PackageNames

  [
      "pkg1",
      "pkg2",
      "pkg3",
  ]
  

Parameters

• arg

  Search term (starts-with)

  • Type: string

Examples

Below you'll find some basic examples for the different types of requests.

Search

• packages containing firefox in the package name or description

  GET/api/v6/search/firefox GET/api/v6/search/name-desc/firefox GET/api/v6/search/name-desc/contains/firefox

• packages whose name start with firefox

  GET/api/v6/search/name/starts-with/firefox

• packages containing both fire and fox in the name

  GET/api/v6/search/name/fire+fox (note that + is a URL-encoded whitespace character)

Info

• a package with the name firefox

  GET/api/v6/info/firefox

• packages providing firefox

  GET/api/v6/info/provides/firefox GET/api/v6/info?by=provides&arg=firefox

• packages co-maintained by someuser

  GET/api/v6/info/comaintainers/someuser GET/api/v6/info?by=comaintainers&arg=someuser

• packages with name firefox or chromium

  GET/api/v6/info?by=name&arg=firefox&arg=chromium

  POST/api/v6/info

  arg=firefox&arg=chromium&by=name
  

Suggest

• packages starting with fire

  GET/api/v6/suggest/fire

• packages whose pkgbase starts with fire

  GET/api/v6/suggest-pkgbase/fire