mirror of
https://gitlab.archlinux.org/archlinux/aurweb.git
synced 2025-02-03 10:43:03 +01:00
docs(api): add documentation for the v6 API
Signed-off-by: moson <moson@archlinux.org>
This commit is contained in:
moson-mo
parent
da6087c88a
commit
15534fbe93
1 changed files with 306 additions and 0 deletions
306
doc/api.md
Normal file
306
doc/api.md
Normal file
|
|
@ -0,0 +1,306 @@
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
* <mark>GET</mark>`/api/v6/search/{arg}`
|
||||||
|
<mark>GET</mark>`/api/v6/search/{by}/{arg}`
|
||||||
|
<mark>GET</mark>`/api/v6/search/{by}/{mode}/{arg}`
|
||||||
|
* `arg` <sub>(path; mandatory)</sub>
|
||||||
|
* `by` <sub>(path; optional)</sub>
|
||||||
|
* `mode` <sub>(path; optional)</sub>
|
||||||
|
|
||||||
|
#### 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
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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
|
||||||
|
* <mark>GET</mark>`/api/v6/info/{arg}`
|
||||||
|
<mark>GET</mark>`/api/v6/info/{by}/{arg}`
|
||||||
|
* `arg` <sub>(path; mandatory)</sub>
|
||||||
|
* `by` <sub>(path; optional)</sub>
|
||||||
|
|
||||||
|
#### Multi lookup
|
||||||
|
* <mark>GET</mark>`/api/v6/info?arg=xyz&arg=abc`
|
||||||
|
<mark>GET</mark>`/api/v6/info?by=provides&arg=xyz&arg=abc`
|
||||||
|
* `arg` <sub>(query-string; mandatory; one or more)</sub>
|
||||||
|
* `by` <sub>(query-string; optional)</sub>
|
||||||
|
|
||||||
|
* <mark>POST</mark>`/api/v6/info`
|
||||||
|
* BODY (`application/x-www-form-urlencoded`):
|
||||||
|
```xml
|
||||||
|
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
|
||||||
|
|
||||||
|
* <mark>GET</mark>`/api/v6/suggest/{arg}`
|
||||||
|
* `arg` <sub>(path; mandatory)</sub>
|
||||||
|
|
||||||
|
* <mark>GET</mark>`/api/v6/suggest-pkgbase/{arg}`
|
||||||
|
* `arg` <sub>(path; mandatory)</sub>
|
||||||
|
|
||||||
|
|
||||||
|
#### Response
|
||||||
|
|
||||||
|
Data is returned in JSON format.
|
||||||
|
|
||||||
|
`200 - OK`
|
||||||
|
|
||||||
|
* PackageNames
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
"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
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/search/firefox`
|
||||||
|
<mark>GET</mark>`/api/v6/search/name-desc/firefox`
|
||||||
|
<mark>GET</mark>`/api/v6/search/name-desc/contains/firefox`
|
||||||
|
|
||||||
|
* packages whose name start with `firefox`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/search/name/starts-with/firefox`
|
||||||
|
|
||||||
|
* packages containing both `fire` and `fox` in the name
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/search/name/fire+fox`
|
||||||
|
(note that `+` is a URL-encoded whitespace character)
|
||||||
|
|
||||||
|
### Info
|
||||||
|
|
||||||
|
* a package with the name `firefox`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/info/firefox`
|
||||||
|
|
||||||
|
* packages providing `firefox`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/info/provides/firefox`
|
||||||
|
<mark>GET</mark>`/api/v6/info?by=provides&arg=firefox`
|
||||||
|
|
||||||
|
* packages co-maintained by `someuser`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/info/comaintainers/someuser`
|
||||||
|
<mark>GET</mark>`/api/v6/info?by=comaintainers&arg=someuser`
|
||||||
|
|
||||||
|
* packages with name `firefox` or `chromium`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/info?by=name&arg=firefox&arg=chromium`
|
||||||
|
|
||||||
|
<mark>POST</mark>`/api/v6/info`
|
||||||
|
```
|
||||||
|
arg=firefox&arg=chromium&by=name
|
||||||
|
```
|
||||||
|
|
||||||
|
### Suggest
|
||||||
|
|
||||||
|
* packages starting with `fire`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/suggest/fire`
|
||||||
|
|
||||||
|
* packages whose pkgbase starts with `fire`
|
||||||
|
|
||||||
|
<mark>GET</mark>`/api/v6/suggest-pkgbase/fire`
|
||||||
Loading…
Add table
Reference in a new issue