Module:Sensitive IP addresses/API/doc

This module provides an API for information about IP addresses that Wikipedia considers sensitive. The intention is that this one API can be used for templates, Lua modules, and software using the MediaWiki Action API such as JavaScript gadgets and bots.

Usage

From templates

Templates wishing to make use of this API need to use an intermediary Lua module to parse the results of API queries. One such module, used to create a wikitable summary of sensitive IPs, exists at Module:Sensitive IP addresses/summary.

From Lua

To load this module from Lua modules, use:

local querySensitiveIPs = require('Module:Sensitive IP addresses/API').query

The query function is called with named parameters. For example:

local result = querySensitiveIPs{
	test = {'1.2.3.4', '5.6.7.8'}
}

Parameters

The following parameters are available to the query function:

• test - an array of IP addresses and/or IP ranges to test for sensitivity. IP addresses and ranges can be IPv4 or IPv6, and ranges must be in CIDR notation.
• entities - an array of entity IDs to get information about. An entity is a country or organization which is considered sensitive, and for which blocks should be handled with care. Entity IDs are defined in Module:Sensitive IP addresses/list along with the rest of the sensitive IP data. For example, ushr is the ID for the United States House of Representatives. If the special ID all is contained in the array, information about all entities will be included in the result.
• format - the format to return results in. Use json to return a JSON-formatted string, and use lua to return a Lua table. If this option is not specified, a Lua table is returned by default.

Results

By default, the query function returns a Lua table, but it can return a JSON object if the format option is set to json. Whether Lua or JSON, the structure of the object returned is similar to the structure of query results from the MediaWiki Action API.

Top-level object

The top level object contains exactly one child object. If the query executed successfully, this object has a key of sensitiveips and contains the query results.

{
    "sensitiveips": {
        [query results]
    }       
}

If there were any errors when executing the query, the child of the top-level object has a key of error and contains error information. The error object has three keys: code, the error ID; info, the error message; and *, a message about where to find the API documentation. The error IDs all have a prefix of "sipa". For example:

{
    "error": {
        "code": "sipa-invalid-test-string",
        "info": "test string #1 'foo' was not a valid IP address or CIDR string",
        "*": "See https://en.wikipedia.org/wiki/Module:Sensitive_IP_addresses/API for API usage"
    }       
}

sensitiveips object

If the query was successful, the sensitiveips child object will be present and can contain the following objects and arrays:

• matches - an array of IP address objects or IP range objects, where the corresponding IP address or IP range string was specified in the test query option, and where Wikipedia regards that IP address or IP range as being sensitive. If no IPs or ranges were tested for, or if no matches were found, this array will not be present in the results.
• matched-ranges - an object with CIDR IP range strings as keys, and matched-range objects as values, where the IP range matches one of the IP addresses or IP ranges tested for with the test query option. If no IPs or ranges were tested for, or if no matches were found, this object will not be present.
• entities - an object with entity IDs as keys, and entity objects as values. An entity is a country or organization which has IP addresses that Wikipedia considers sensitive. Entity IDs are defined in Module:Sensitive IP addresses/list; for example, ushr is the ID for the United States House of Representatives. Entities will be included in this object if an IP range belonging to them is matched by one of the IP addresses or IP ranges tested for with the test query option, or if their entity ID is specified in the entities query option.
• entity-ids - an array of entity ID strings, in the order they are defined in Module:Sensitive IP addresses/list. The entity IDs in this array correspond one-to-one with the entity ID keys of the entities result object. This array can be useful for outputting the IDs in the same order that they were defined in the list.