README ¶
= xq-api(8) Noel Cower :doctype: manpage :manmanual: XQ-API :mansource: XQ-API :man-linkstyle: pass:[blue R < >] // vim: set sw=4 ts=4 et tw=80 : == Name xq-api - serve XBPS repodata over HTTP == Synopsis `xq-api [OPTIONS] [--] <REPODATA...>` == Description *xq-api* serves XBPS repodata over HTTP, formatting its responses as JSON. It loads repodata into memory prior to serving it. == Options `-h`, `-help`:: Print all CLI flags. This includes glog flags not described below that are primarily used for debugging and log rotation. `-net`=_{network}_:: The type of network address to listen on. May be one of `unix` (Unix domain socket), `tcp`, `tcp4` (IPv4 only), or `tcp6` (IPv6 only). Defaults to `tcp`. `-listen`=_{addr}_:: The address to listen on. If `-net` is `unix`, this is a path to the Unix domain socket to create. Defaults to `127.0.0.1:8197`, regardless of what `-net` is. `-max-queries`=_{n}_:: The maximum number of query requests that can run in parallel. If more than `n` query requests are made in parallel, they will block until others complete. Defaults to `16`. `-reload-every`=_{duration}_:: Reload repository data every _duration_. If the duration is zero or a negative interval, automatic reloading is disabled. By default, automatic reloading is disabled. `-log-access`=_{t|f}_:: Whether to emit access logs. Requests that get a 404, 304, or 0 response are not logged. If passed without a value, `t` is assumed. Defaults to `f`. `-logtostderr`=_{t|f}_:: Whether to log to standard error or files. If `f`, logs are written to `log_dir` (below). Defaults to `t`. `-alsologtostderr`=_{t|f}_:: Whether to log to stderr in addition to files, if `logtostderr` is `f`. Defaults to `f`. `-log_dir`=_{logdir}_:: The directory to write log files to. Only used if `logtostderr` is `f`. If `dir` cannot be used, it will fall back to the temporary directory. Defaults to the temporary directory. In addition, there are other common glog flags that are detailed in usage output. == Signals `xq-api` responds to HUP by reloading the repodata it was given on the command line. After the server has been started, it responds to TERM and INT signals by attempting to gracefully shut down the server. == Repodata When passing repodata to `xq-api`, it expects to receive either a directory containing one or more repodata files or an individual repodata file. For example, to serve repodata from the current machine, one can start xq-api with the following (which will match the vast majority of repositories, if any are synced): $ xq-api /var/db/xbps/http*/*-repodata loading repodata... loading /var/db/xbps/http___alpha_de_repo_voidlinux_org_current/x86_64-repodata ... Alternatively, you can pass directories: $ xq-api /var/db/xbps/http* loading repodata... loading /var/db/xbps/http___alpha_de_repo_voidlinux_org_current/x86_64-repodata ... Symbolic links are not followed when walking a directory to find repodata. If you need this, please open an issue on <https://github.com/nilium/xq-api>. == Responses All responses from xq-api, with the exception of redirects, yield JSON output of the form `{"data": <RequestedThing>}`, where RequestedThing is either an object or an array. Unexpected or invalid paths respond with 404 and an empty `{}` object. == Paths The following paths are available in xq-api. [NOTE] All example responses are pretty-printed for convenience. xq-api does not pretty-print JSON. === /v1/archs Responds with an array of strings identifying valid architectures for use with other paths. .Example [source,json] ---- { "data": [ "aarch64", "aarch64-musl", "armv6l", "armv6l-musl", "armv7l", "armv7l-musl", "i686", "i686-musl", "x86_64", "x86_64-musl" ] } ---- === /v1/packages/{arch} Responds with an array of strings identifying valid packages for `arch`. The array is lexicographically ordered case-sensitively. .Parameters `arch`:: An architecture served by xq-api. Valid architectures are returned from `/v1/archs`. .Example [source,json] ---- { "data": [ "0ad", "0ad-32bit", "0ad-data", "2048-qt", "2bwm", "... EXAMPLE ELLIPSIZED ...", "zzuf", "zzuf-32bit" ] } ---- === /v1/packages/{arch}/{package} Responds with an object describing the package from repodata. This is intended to be the same as what you can see by looking up the package with xbps-query(1) with some alterations: * `pkgver` is split into `name`, `version`, and `revision` JSON fields. `pkgver` itself is not served. * Field names with hyphens in xbps-query have underscores in xq-api (such as `filename_sha256`). This is for convenience when using these fields in languages like Javascript. * Timestamps are formated in RFC 3339. This is, again, for convenience in working with other languages. .Parameters `arch`:: An architecture served by xq-api. Valid architectures are returned from `/v1/archs`. `package`:: A package under `arch`. Valid package names are retruend from `/v1/packages/{arch}`. .Data Fields Any field that is empty, zero, or false is omitted from the response as it is the default value for that field. In the list below, `[]string` is an array of strings. * *name*: string * *version*: string * *revision*: integer * *repository*: string * *architecture*: string * *build_date*: string (RFC 3339 timestamp) * *build_options*: string * *filename_sha256*: string * *filename_size*: integer * *homepage*: string (url) * *installed_size*: integer * *license*: string * *maintainer*: string * *short_desc*: string * *preserve*: bool (only set if `true`) * *source_revisions*: string * *run_depends*: []string * *shlib_requires*: []string * *shlib_provides*: []string * *conflicts*: []string * *reverts*: []string * *replaces*: []string * *alternatives*: map[string][]string (a map of strings to arrays of strings, such as `{ "key": ["values"] }`) * *conf_files*: []string .Example [source,json] ---- { "data": { "name": "retrap", "version": "1.0.1", "revision": 2, "repository": "current", "architecture": "x86_64", "build_date": "2019-01-10T09:03:00Z", "filename_sha256": "35eb56b97d20b04afe6bb40f471b849e4f4022d999bbbc0e4b48fc78e68ffe14", "filename_size": 1065888, "homepage": "https://github.com/nilium/retrap", "installed_size": 2365759, "license": "BSD-2-Clause", "maintainer": "Noel Cower <ncower@gmail.com>", "short_desc": "Remap signals and forward them to a child process", "run_depends": [ "glibc>=2.28_1" ], "shlib_requires": [ "libpthread.so.0", "libc.so.6" ] } } ---- === /v1/query/{arch}?q={query} Responds with an array containing packages under `arch` that match the `query`. The resulting package objects contain only a subset of their full fields. .Parameters `arch`:: An architecture served by xq-api. Valid architectures are returned from `/v1/archs`. `query`:: A query string to filter results by. Only `pkgver` (the combination of `name`, `version`, and `revison`) and `short_desc` are searched. If empty, all packages are returned. .Data Fields * *name*: string * *version*: string * *revision*: integer * *filename_size*: integer (bytes) * *repository*: string (omitted if empty) * *short_desc*: string (omitted if empty) .Example [source,json] ---- { "data": [ { "name": "retrap", "version": "1.0.1", "revision": 2, "filename_size": 1065888, "repository": "current", "short_desc": "Remap signals and forward them to a child process" } ] } ---- == Building xq-api To build xq-api, you can use make: $ make xq-api And to build the manpage: $ make xq-api.8 Or, to build both: $ make Otherwise, to build xq-api with the Go tool from within the source tree: $ go build go.spiff.io/xq-api == Reporting Issues If you encounter a bug in xq-api, or want to request a feature or something else, please open an issue on the project website if one doesn't already exist: <https://github.com/nilium/xq-api>. You can also submit pull requests through the project site.
Documentation ¶
There is no documentation for this package.
Click to show internal directories.
Click to hide internal directories.