Aurweb RPC interface (Português)

Status de tradução:
Esse artigo é uma tradução de
Aurweb RPC interface
. Data da última tradução: 2022-11-16. Você pode ajudar a sincronizar a tradução, se houver
alterações
na versão em inglês.
Artigos relacionados
Interface web de repositórios oficiais
A
interface RPC do Aurweb
é uma interface
RPC
leve para o
AUR
. Consultas são enviadas como requisições HTTP GET e respostas do servidor com
JSON
.
Nota
Esse artigo descreve a v5 da API de Interface do RPC, conforme atualizado com o AUR v4.7.0 em 7 de julho de 2018.
Uso da API
Tipos de consulta
Há dois tipos de consultas:
search
info
search
Pesquisas por pacote podem ser feitas enviando requisições na forma:
/rpc/?v=5&type=search&by=
campo
&arg=
palavras-chave
sendo
palavras-chave
o argumento de pesquisa e
campo
um dos valores a seguir:
name
(pesquisa pelo nome do pacote apenas)
name-desc
(pesquisa pelo nome e descrição do pacote)
maintainer
(pesquisa pelo mantenedor do pacote)
depends
(pesquisa pacotes que são dependências por palavras-chaves)
makedepends
(pesquisa pacotes que são dependências para compilação por palavras-chaves)
optdepends
(pesquisa pacotes que são dependências opcionais por palavras-chaves)
checkdepends
(pesquisa pacotes que são dependências para verificação por palavras-chaves)
O parâmetro
by
pode ser pulado, tendo como padrão
name-desc
.
tipos possíveis de retorno são
search
e
error
.
Se uma pesquisa de mantenedor for realizada e o argumento de pesquisa for deixado vazio, uma lista de pacotes órfãos é retornada.
Exemplos:
Pesquisar por
pacote
:
https://aur.archlinux.org/rpc/?v=5&type=search&arg=
pacote
Pesquisar por pacotes mantidos por
usuário
:
https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=
usuário
Pesquisar por pacotes que têm
pacote
como `makedepends`:
https://aur.archlinux.org/rpc/?v=5&type=search&by=makedepends&arg=
pacote
Pesquisar com chamadas:
https://aur.archlinux.org/rpc/?v=5&type=search&arg=
pacote
&callback=jsonp1192244621103
info
Informações de pacote podem ser obtidas enviando requisições na forma:
/rpc/?v=5&type=info&arg[]=
pkg1
&arg[]=
pkg2
&…
sendo
pkg1
,
pkg2
, … correspondências exatas de nomes de pacotes para obter detalhes de pacote.
Tipos de retorno possível são
multiinfo
e
error
.
Exemplos:
Informação para um único pacote:
https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=
pacote
Informação para vários pacotes:
https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=
pacote1
&arg[]=
pacote2
Tipos de retorno
A carga de retorno é de um formato, e atualmente tem três tipos principais. A resposta sempre retornará um tipo para que o usuário possa determinar se o resultado de uma operação foi um erro ou não.
O formato da carga retornada é:
{"version":5,"type":
TipoRetornado
,"resultcount":0,"results":
DadosRetornados
}
TipoRetornado
é uma string e o valor é um entre:
search
multiinfo
error
Dados de retorno
O tipo de
DadosRetornados
é um vetor de dicionário de objetos para os
TipoRetornado
search
e
multiinfo
e um vetor vazio para
TipoRetornado
error
.
Para o
TipoRetornado
search
,
DadosRetornados
pode conter os seguintes campos:
ID
Name
PackageBaseID
PackageBase
Version
Description
URL
NumVotes
Popularity
OutOfDate
Maintainer
FirstSubmitted
LastModified
URLPath
Para os
TipoRetornado
info
e
multiinfo
,
DadosRetornados
também pode conter os seguintes campos:
Depends
MakeDepends
OptDepends
CheckDepends
Conflicts
Provides
Replaces
Groups
License
Keywords
Campos que um pacote não contém serão omitidos da saída.
error
O tipo
error
possui uma string de resposta de erro como o valor retornado. Uma resposta de erro pode ser retornada de um tipo de consulta
search
ou
info
.
Exemplo de
TipoRetornado
error
:
{"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}
search
O tipo
search
é resultado retornado de uma operação de requisição de pesquisa.
Exemplo de
TipoRetornado
search
:
{"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}
info
O tipo
multiinfo
é o resultado de uma operação de requisição de informações.
Exemplo de
TipoRetornado
multiinfo
:
{
    "version":5,
    "type":"multiinfo",
    "resultcount":1,
    "results":[{
        "ID":229417,
        "Name":"cower",
        "PackageBaseID":44921,
        "PackageBase":"cower",
        "Version":"14-2",
        "Description":"A simple AUR agent with a pretentious name",
        "URL":"http:\/\/github.com\/falconindy\/cower",
        "NumVotes":590,
        "Popularity":24.595536,
        "OutOfDate":null,
        "Maintainer":"falconindy",
        "FirstSubmitted":1293676237,
        "LastModified":1441804093,
        "URLPath":"\/cgit\/aur.git\/snapshot\/cower.tar.gz",
        "Depends":[
            "curl",
            "openssl",
            "pacman",
            "yajl"
        ],
        "MakeDepends":[
            "perl"
        ],
        "License":[
            "MIT"
        ],
        "Keywords":[]
    }]
 }
jsonp
Se você está trabalhando com uma página javascript e precisa de um mecanismo de retorno de chamada do JSON, você pode fazê-lo.
Você só precisa fornecer uma variável de retorno de chamada adicional. Esse retorno de chamada geralmente é tratado através da biblioteca javascript, mas aqui é um exemplo.
Consulta exemplo:
https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103
Resultado exemplo:
/**/jsonp1192244621103({"version":5,"type":"search","resultcount":1,"results":[{"ID":250608,"Name":"foobar2000","PackageBaseID":37068,"PackageBase":"foobar2000","Version":"1.3.9-1","Description":"An advanced freeware audio player (uses Wine).","URL":"http:\/\/www.foobar2000.org\/","NumVotes":39,"Popularity":0.425966,"OutOfDate":null,"Maintainer":"supermario","FirstSubmitted":1273255356,"LastModified":1448326415,"URLPath":"\/cgit\/aur.git\/snapshot\/foobar2000.tar.gz"}]})
Isso chamaria automaticamente a função JavaScript
jsonp1192244621103
com o parâmetro definido para os resultados da chamada RPC.
Limitações
Requisições de HTTP GET são limitadas a uma URI com tamanho máximo de 8190 bytes. Porém, a instância oficial do AUR, no servidor nginx com HTTP/2, usa o limite de
tamanho máximo padrão de URI
de 4443 bytes. Requisições de informações com mais do que 200 pacotes como argumento precisarão ser divididos.
Consultas de pesquisa devem ter pelo menos dois caracteres.
As pesquisas falharão se contiverem 5000 ou mais resultados.
A taxa de API está limitada a um máximo de 4000 requisições por dia por IP.
Nota
Alguns dados estão disponíveis nos
arquivos de metadados do AUR
para processamento em lote.
Clientes de referência
Às vezes, as coisas são mais fáceis de entender com exemplos. Algumas implementações de referência (jQuery, python, ruby) estão disponíveis na seguinte URL:
https://github.com/cactus/random/tree/2b72a1723bfc8ae64eed6a3c40cb154accae3974/aurjson_examples