#mediawiki #api #types

mwapi_responses

Automatically generate strict types for MediaWiki API responses

4 releases

Uses new Rust 2021

0.2.2 Nov 15, 2021
0.2.1 Nov 8, 2021
0.2.0 Nov 1, 2021
0.1.0 Oct 24, 2021

#444 in Web programming

Download history 11/week @ 2021-10-19 16/week @ 2021-10-26 49/week @ 2021-11-02 47/week @ 2021-11-09 37/week @ 2021-11-16 19/week @ 2021-11-23

165 downloads per month
Used in mwbot

GPL-3.0-or-later

55KB
786 lines

mwapi_responses

crates.io pipeline status coverage report

The mwapi_responses crate provides strict typing for dynamic MediaWiki Action API queries. See the documentation (master) for more details.

License

mwapi_responses is (C) 2020-2021 Kunal Mehta legoktm@debian.org under the GPL v3 or any later version.


lib.rs:

mwapi_responses

The mwapi_responses crate provides strict typing for dynamic MediaWiki Action API queries. The goal is to faithfully represent what the API's JSON structure is while saving people from manually writing out serde-compatible structs for every query.

A list module:

use mwapi_responses::prelude::*;
#[query(
    list = "logevents",
    leaction = "newusers/create",
    leprop = "user|type",
    lelimit = "100"
)]
struct Response;

This creates a Response struct that matches the API response for the given query. Roughly, it will expand to:

#[derive(Debug, Clone, serde::Deserialize)]
pub struct Response {
    #[serde(default)]
    pub batchcomplete: bool,
    #[serde(rename = "continue")]
    #[serde(default)]
    pub continue_: HashMap<String, String>,
    pub query: ResponseBody,
}

#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseBody {
    pub logevents: Vec<ResponseItemlogevents>,
}

#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseItemlogevents {
    pub user: String,
    #[serde(rename = "type")]
    pub type_: String,
}

Or getting various properties from pages:

use mwapi_responses::prelude::*;
#[query(
    prop="info|revisions",
    inprop="url",
    rvprop="ids"
)]
struct Response;

which expands to:

#[derive(Debug, Clone, serde::Deserialize)]
pub struct Response {
    #[serde(default)]
    pub batchcomplete: bool,
    #[serde(rename = "continue")]
    #[serde(default)]
    pub continue_: HashMap<String, String>,
    pub query: ResponseBody,
}

#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseBody {
    pub pages: Vec<ResponseItem>,
}

#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseItem {
    pub canonicalurl: String,
    pub contentmodel: String,
    pub editurl: String,
    pub fullurl: String,
    pub lastrevid: Option<u32>,
    pub length: Option<u32>,
    #[serde(default)]
    pub missing: bool,
    #[serde(default)]
    pub new: bool,
    pub ns: i32,
    pub pageid: Option<u32>,
    pub pagelanguage: String,
    pub pagelanguagedir: String,
    pub pagelanguagehtmlcode: String,
    #[serde(default)]
    pub redirect: bool,
    pub title: String,
    pub touched: Option<String>,
    #[serde(default)]
    pub revisions: Vec<ResponseItemrevisions>,
}

#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseItemrevisions {
    pub parentid: u32,
    pub revid: u32,
}

In both cases, you can easily iterate over ResponseItemlogevents and ResponseItem respectively by calling Response::items().

Field naming

Fields are renamed if they can't be used as fields in Rust, like continue or type. In these cases, an underscore is appended.

Supported modules

The metadata that powers this crate is manually gathered. To see if a specific module is supported, look at the Git repository. Contributions for missing modules or parameters are always welcome.

Library agnostic

This crate does not implement or support any one specific API library, rather it aims to just provide types and helpers to enable you to run your API requests however you'd like.

Helper functions

To avoid repeating the parameters in multiple places, you can call Response::params() to get a &[(&str, &str)] of the parameters that were provided to the #[query(...)] macro.

Not yet implemented

There is no special support for continuing queries. In the future some merge()-like function might be provided.

Dependencies

~0.9–1.6MB
~38K SLoC