API:Tutorial Action API
Esta página é parte da documentação da API action do MediaWiki. |
Neste tutorial, você aprenderá sobre a função Action API do MediaWiki, como usá-la, formato de solicitação, uma consulta simples e exemplos de projetos usando Action API.
Overview of the MediaWiki Action API
A API é uma REST completa, web service que permite aos usuários realizar certas ações wiki como criação de página, autenticação, análise, pesquisa, etc. API:Página principal é um bom ponto de partida para entender a API.
Seu programa envia solicitações à API para obter acesso aos recursos da wiki. Por exemplo, efetua autenticação/login em uma wiki, cria uma página, edita, pesquisa um título, pesquisa um texto de conteúdo, analise o conteúdo. A API de ação está disponível para desenvolvedores terceirizados, desenvolvedores de extensões Wikimedia e administradores de sites wiki.
On the right sidebar of this page, there are many features that are supported by the API, grouped by category. Antes de enviar solicitações para um servidor wiki, primeiro leia as páginas de visão geral, como formatos de dados, erros e avisos e as Perguntas frequentes da API.
Como usar a API
Como usuário você pode solicitar dados ao servidor noformato HTTP e obter a resposta no formato padrão (normalmente JSON). Uma solicitação consiste em um endpoint e um conjunto de parâmetros. Existem dois tipos de solicitação que podem ser feitas:GET and POST. Para uma solicitação GET, um parâmetro conteria uma string de consulta na URL. Para uma solicitação POST, os parâmetros precisam estar no formato JSON.
Formato da solicitação
Todos as wikis da Wikimedia têm endpoints neste formato http://example.org/w/api.php
. Para operar no site principal do MediaWiki ou na Wikipedia em inglês, use o endpoint relacionado. Por exemplo, a Wikipédia em inglês é https://en.wikipedia.org/w/api.php
. Para testar novas contas ou testar edições em páginas, use o endpoint do wiki de teste https://test.wikipedia.org/w/api.php
.
Na string de consulta no URL, adicione o parâmetro action
. Ele informa para a API qual ação executar. A ação mais popular é query
(o URL conteria action=query
), que permite buscar dados de uma wiki. Após o parâmetro action
, adicione outro parâmetro para indicar qual dos três tipos de módulo de consulta você deseja executar:
prop
- Obter as propriedades da páginalist
- Lista de páginas que correspondem a um critério.meta
- Obter meta informações sobre a wiki e o usuário
Por fim, inclua o parâmetro format
, que informa à API em qual formato obter os resultados. O formato recomendado é o JSON (a API suportou outros formatos de saída no passado, mas não são recomendados).
![Request format](http://upload.wikimedia.org/wikipedia/commons/thumb/9/97/Request_format.svg/500px-Request_format.svg.png)
Uma pesquisa simples
Vamos dar um exemplo de uma pesquisa simples (em inglês: query) para entender como seria uma solicitação GET e sua resposta típica no contexto da Action API.
Vamos pesquisar um título em uma wiki, usaremos o módulo search
documentado em API:Search .
Solicitações GET
Para pesquisar títulos de páginas ou um conteúdo correspondente a Craig Noone
, o formato da URL para fazer uma solicitação HTTP GET seria:
Explicação de cada parte da URL:
http://en.wikipedia.org/w/api.php
é o ponto final principal. Neste caso, é a Wikipédia em inglês.action=query
é para pesquisar dados do wiki.list=search
é para obter uma lista de páginas que correspondem a um critério.srsearch=Craig%20Noone
indica o título da página ou o conteúdo a ser pesquisado. O%20
indica um caractere de espaço em uma URL.format=json
indica a saída JSON (formato de saída recomendado).
Resposta
A resposta é um documento no formato JSON com uma lista de títulos de páginas que correspondem a Craig Noone:
{
"batchcomplete": "",
"continue": {
"sroffset": 10,
"continue": "-||"
},
"query": {
"searchinfo": {
"totalhits": 210
},
"search": [
{
"ns": 0,
"title": "Craig Noone",
"pageid": 18846922,
"size": 22548,
"wordcount": 1771,
"snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
"timestamp": "2018-11-02T22:25:45Z"
},
{
"ns": 0,
"title": "Noone",
"pageid": 32906333,
"size": 553,
"wordcount": 64,
"snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to: <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
"timestamp": "2015-08-16T05:16:17Z"
}
...
]
}
}
Examples of projects using Action API
Alguns exemplos de projetos na Wikimedia que usam Action API:
- Wikipedia iOS App, em que um dos recursos é pesquisar páginas wiki perto de sua localização.
- Bots que operam em uma wiki, o Pywikibot é uma estrutura de bot desenvolvido com a linguagem de programação Python, criando uma interface com a API MediaWiki que muitos desenvolvedores de bot usam.
- Uso da API na visualização de dados obtidos de uma wiki. Como esta visualização elegante que mostra edições em tempo real feitas na Wikipedia.
Ajuda adicional
- Vários sites estão usando o MediaWiki. Todos eles podem estar executando uma versão diferente do MediaWiki e, por sua vez, a API. Alguns parâmetros de módulo suportados em uma versão podem ser obsoletos ou removidos em outras. Você pode ver as diferenças na documentação de cada módulo via API help module.
- Se quiser fazer muitas consultas com a API, ou talvez executar bots muito ativos, converse com os administradores da wiki com antecedência, para que eles não sejam bloqueados. Veja a lista de Administradores de projetos da Wikimedia. Leia mais sobre este tópico em API:Etiqueta .
- Todas as ações de modificação de dados, como registrar, editar ou mover uma página e observar ou patrulhar as alterações exigem tokens. Obtenha tokens por meio de API:Tokens para prosseguir.
Recursos
- Use Special:APISandbox para experimentar a Action API. Você pode brincar com as ações suportadas, especificar um valor para os parâmetros e enviar consultas à API para ver os resultados na mesma página.
- Wikimedia dumps para trabalhar com eles localmente.
- Leia os tutoriais: Uma introdução às API e O que é REST, explicação para iniciantes.
- MediaWiki API help fornece uma documentação da API, gerada automaticamente que indica todos os módulos suportados.
- API:Página principal fornece um resumo da API.
- Introdução à API do MediaWiki por User:Roan_Kattouw_(WMF) no Hackathon de São Francisco (2012). Este tutorial possui vídeo.
- GitHub: MediaWiki API Demos