API:Main page/pt


 * Esta é uma apresentação da API "operacional". Encontra no menu à direita subtópicos com mais detalhes e também outras API.

A API operacional do MediaWiki é um serviço web para acesso conveniente à funcionalidade, dados e metadados de uma wiki usando o protocolo HTTP através de um URL, e está normalmente localizada no ficheiro. Os clientes solicitam "operações" particulares especificando um parâmetro, normalmente   para obter informação. Esta API era conhecida como  a  API do MediaWiki, mas entretanto foram disponibilizadas outras API para interagir com o MediaWiki, tais como a RESTBase e o serviço de consulta Wikidados.

Introdução
A API operacional do MediaWiki pode ser usada para monitorizar uma instalação MediaWiki, ou criar um robô para atividades automáticas de manutenção. A API dá acesso direto de alto nível ao conteúdo das bases de dados do MediaWiki. Aplicações cliente podem autenticar-se numa wiki, obter dados e publicar alterações automaticamente, enviando pedidos HTTP ao serviço web. Os clientes suportados incluem robôs, clientes simples em JavaScript baseados em tecnologias web, como popups de navegação ou o LiveRC, aplicações de utilizadores finais como Vandal Fighter e outros sites da Internet (utilitários [//tools.wmflabs.org Toolforge]).

Nas instalações novas do MediaWiki, o serviço web é ativado por padrão, mas os administradores podem desativá-lo.

O MediaWiki tem duas outras interfaces externas:


 * A página Special:Export, que permite a exportação em bloco do conteúdo de uma wiki no formato XML. Consulte para mais informações.
 * A interface web padrão (que provavelmente está a utilizar neste momento para ver esta página). Consulte para informações sobre a utilização da interface web.

Um exemplo simples
Este URL diz ao serviço web da API da Wikipédia de língua inglesa para enviar de volta o conteúdo da página principal:

Pode usar qualquer linguagem de programação para enviar um pedido GET de HTTP para este URL (ou apenas visitar o link no seu browser) e obterá de volta um documento JSON que inclui o texto em notação wiki da página «Main Page». Alterando o formato para  obtém-se em resultado um HTML formatado para facilitar a despistagem de erros.

Vamos analisar o URL para demonstrar como ele funciona.

O ponto de destino
O «ponto de destino» é este. É como se fosse a página principal da API web do MediaWiki. Este URL é o URL base para a API da Wikipédia inglesa, tal como  é o URL base para o respetivo site na Internet.

Se está a escrever um programa para usar a Wikipédia inglesa, todos os URL que construir irão começar por este URL base. Se estiver a usar uma instalação diferente do MediaWiki, terá de encontrar o ponto de destino dela e usá-lo. Todas as wikis da Wikimedia têm pontos de destino que seguem este padrão:

A partir da versão, temos um processo RSD de descoberta do ponto de destino: procure o elemento  no código-fonte HTML de qualquer página e extraia o URL que conduz ao ficheiro  ; o link que encontrar conterá informação adicional. Por exemplo, nesta wiki o elemento  é:

Não há outra forma segura de localizar o ponto de destino de qualquer wiki. Se tiver sorte, ou o caminho completo até o ficheiro index.php não está ocultado por detrás de regras de reescrita estranhas e neste caso só precisa de usar um link "edit" (ou history) e substituir index.php (etc.) por api.php, ou pode usar o caminho para scripts padrão (como ).

Passemos aos parâmetros que constam no texto de consulta do URL.

O formato
Isto diz à API que queremos que os dados sejam enviados de volta no formato JSON. Também pode tentar  para obter uma versão do HTML que facilita o processo de despistagem de erros. A API suporta outros formatos de saída, tais como XML e PHP nativo, mas há planos de remover os formatos menos populares (T95715), por isso pode não ser aconselhável usá-los.

A operação
A API web do MediaWiki implementa dezenas de operações e as extensões implementam muitas mais; a ajuda da API, que é gerada dinamicamente, documenta todas as operações disponíveis numa wiki. Neste caso, estamos a usar a operação «query» para obter alguma informação. A operação «query» é uma das operações mais importantes da API, e em si mesma tem uma documentação vasta. O que se segue é apenas a explicação de um exemplo simples.

Parâmetros específicos da operação
O resto do URL de exemplo contém parâmetros usados pela operação «query». Aqui, estamos a informar à API web que queremos informação sobre a página da wiki com o título «Main Page». (O %20 resulta da codificação por cento do carácter espaço.) Se precisa de consultar várias páginas, coloque-as todas num único pedido, para otimizar recursos na utilização da rede e do servidor:. Consulte a documentação de query para mais detalhes.

Pode solicitar muitos tipos de informação, ou propriedades, acerca de uma página. Este parâmetro diz à API web que queremos informação sobre uma revisão específica da página. Como não especificámos nenhuma informação da revisão, A API dá-nos informação sobre a revisão mais recente &mdash; a página principal da Wikipédia inglesa tal como ela está neste momento.

Finalmente, este parâmetro diz à API que queremos o conteúdo da última revisão da página. Se tivéssemos passado, obteríamos o conteúdo mais recente da página e o nome do utilizador que criou a revisão mais recente.

Novamente, isto é só um exemplo. As consultas são explicadas em mais detalhe aqui, e a página de referência da API lista todas as operações possíveis, todos os valores possíveis para, e por aí adiante.



Começar
Antes de começar a usar a API web do MediaWiki, leia estes documentos:


 * A FAQ.
 * A página sobre formatos de entrada e saída
 * A página sobre erros e avisos
 * Quaisquer normas que se apliquem à wiki a que pretende aceder, tais como os termos e condições de uso e as normas de uso de marcas registadas das wikis da Wikimedia Foundation. Estas condições aplicam-se a si quando acede ou edita usando a API, tal como se aplicam ao utilizar o browser.

Para além disto, aquilo que necessita de ler depende do que pretende fazer. No menu à direita encontra ligações para documentação mais detalhada e específica, e abaixo são apresentadas mais algumas regras gerais.

Identificar o seu cliente
Quando enviar pedidos de HTTP ao serviço web da API do MediaWiki, certifique-se de que especifica um cabeçalho  que identifica devidamente o seu cliente. Não use o  padrão fornecido pela sua biblioteca de cliente, mas crie um cabeçalho personalizado que identifica o seu script ou serviço e fornece uma forma qualquer de contactá-lo (por exemplo, o seu e-mail).

Uma linha User-Agent de exemplo pode ser assim: MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4

Nas wikis da Wikimedia, se não fornecer um cabeçalho, ou se aquele que fornecer estiver vazio ou for genérico, o seu pedido irá falhar com o erro HTTP 403 (cf. User-Agent policy). Outras instalações do MediaWiki podem ter normas semelhantes.

Se está a chamar a API a partir de JavaScript via o browser, não pode alterar o cabeçalho : o browser usará o seu próprio. Para contornar este problema, use o cabeçalho.

No PHP, pode identificar o seu user-agent com código como este:

Ou, se usar cURL:

Autenticação
O seu cliente provavelmente precisará de entrar no MediaWiki, possivelmente através da sua conta de utilizador. Consulte a página de autenticação do manual para mais detalhes.

Etiqueta da API
Leia também: API:Etiqueta

Se ou seus pedidos obtiverem dados que podem ser armazenados em cache, deve providenciar para que o sejam, de forma a evitar pedir os mesmos dados repetidamente. Pode encontrar mais informações sobre limitações de pedidos, concorrência e etiqueta da API, em API:Etiqueta. Alguns clientes têm a capacidade de armazenar dados em cache eles mesmos, mas para outros (em particular, clientes JavaScript) isto não é possível.

De acordo com a especificação HTTP, os pedidos POST não podem ser armazenados em cache. Portanto, quando está a ler dados da API web, deve usar pedidos GET e não POST.

Note também que um pedido não pode ser servido pela API a partir da cache, a menos que o URL seja exatamente o mesmo. Se pedir, e armazenar o resultado em cache, pedir   não passará pela cache &mdash; embora o MediaWiki devolva os mesmos dados!

Deve ter o cuidado de normalizar os URL que envia ao serviço web do MediaWiki, de modo que a introdução de dados ligeiramente diferentes pelo utilizador não cause pedidos HTTP desnecessários. Pode normalizar listas de títulos de páginas, removendo duplicados e ordenando os títulos por ordem alfabética. Técnicas semelhantes funcionam para outros tipos de dados.

Links úteis
A barra de menu do lado direito desta página contém ligações para documentação mais detalhada e específica. Encontra abaixo mais alguns links relacionados com a API na sua totalidade.


 * A área de testes da API, disponível em todas as wikis da Wikimedia, torna fácil tentar operações diferentes de forma interativa.
 * [//en.wikipedia.org/w/api.php O manual de referência da API] contém descrições geradas de forma automática para todas as operações e parâmetros.
 * Ligue-se à informação da Wikipédia usando PHP e a API do MediaWiki (artigo da IBM developerWorks, 17 de maio de 2011)
 * Ligue-se à Wikipédia usando Java e a API do MediaWiki (6 de abril de 2012)
 * Lista de divulgação para notificações e perguntas: Lista de divulgação da API
 * Lista de divulgação de baixo tráfego, só para anúncios (todas as publicações nesta lista também são publicadas em mediawiki-api): mediawiki-api-announce
 * Consulte e reporte defeitos da API no projeto MediaWiki-API no Phabricator (Ao reportar defeitos novos, não se esqueça de adicionar MediaWiki-API aos projetos)
 * — A estrutura (schema) da base de dados atual do MediaWiki
 * — A estrutura (schema) da base de dados atual do MediaWiki

Links arquivados

 * Discussão da API em 2006