Content deleted Content added
add IP range and entity object descriptions |
m change source to syntaxhighlight |
||
| (10 intermediate revisions by 3 users not shown) | |||
Line 1:
{{Module rating|protected}}
{{Used in system}}
This module provides an API for information about [[WP:SIP|IP addresses that Wikipedia considers sensitive]]. The intention is that this one API can be used for templates, Lua modules, and software using the [[mw:API:Main page|MediaWiki Action API]] such as JavaScript gadgets and bots.
Line 11 ⟶ 13:
To load this module from Lua modules, use:
<
local querySensitiveIPs = require('Module:Sensitive IP addresses/API').query
</syntaxhighlight>
The query function is called with named parameters. For example:
<
local result = querySensitiveIPs{
test = {'1.2.3.4', '5.6.7.8'}
}
</syntaxhighlight>
== Parameters ==
Line 39 ⟶ 41:
The top level object contains exactly one child object. If the query executed successfully, this object has a key of <code>sensitiveips</code> and contains the query results.
<
{
"sensitiveips": {
Line 45 ⟶ 47:
}
}
</syntaxhighlight>
If there were any errors when executing the query, the child of the top-level object has a key of <code>error</code> and contains error information. The error object has three keys: <code>code</code>, the error ID; <code>info</code>, the error message; and <code>*</code>, a message about where to find the API documentation. The error IDs all have a prefix of "sipa". For example:
<
{
"error": {
Line 57 ⟶ 59:
}
}
</syntaxhighlight>
===
If the query was successful, the <code>sensitiveips</code> child object will be present and can contain the following objects and arrays:
Line 91 ⟶ 93:
* <code>name</code> - the name of the entity. This is a plain string, containing no wikitext, and is always present.
* <code>description</code> - a description of the entity. This is a string, and may contain wikitext. This field is optional, and may not be present.
* <code>reason</code> - the reason that the entity's IP ranges are sensitive. The possible reasons are <code>{{#invoke:Sensitive IP addresses/API|_getSensitivityReasons|</code>, <code>|</code> and <code>}}</code>.
* <code>ipv4-ranges</code> - an array of IPv4 CIDR strings that belong to the entity, and are considered as sensitive by Wikipedia. This field is optional, and may not be present.
* <code>ipv6-ranges</code> - an array of IPv6 CIDR strings that belong to the entity, and are considered as sensitive by Wikipedia. This field is optional, and may not be present.
* <code>notes</code> - notes about the entity or its ranges. This field is optional, and may not be present.
== Examples ==
Here are some examples of some queries from Lua and the results they produce.
=== No matches ===
Query:
<syntaxhighlight lang="lua">
querySensitiveIPs{
test = {'1.2.3.4'}
}
</syntaxhighlight>
Result:
<syntaxhighlight lang="lua">
{
["sensitiveips"] = {
}
}
</syntaxhighlight>
=== One match ===
Query:
<syntaxhighlight lang="lua">
querySensitiveIPs{
test = {'156.33.5.76'}
}
</syntaxhighlight>
Result:
<syntaxhighlight lang="lua">
{
["sensitiveips"] = {
["matches"] = {
{
["type"] = "ip",
["ip"] = "156.33.5.76",
["ip-version"] = "IPv4",
["matches-range"] = "156.33.0.0/16",
["entity-id"] = "ussenate",
},
},
["matched-ranges"] = {
["156.33.0.0/16"] = {
["range"] = "156.33.0.0/16",
["ip-version"] = "IPv4",
["entity-id"] = "ussenate",
},
},
["entities"] = {
["ussenate"] = {
["id"] = "ussenate",
["name"] = "United States Senate",
["description"] = "the [[United States Senate]]",
["reason"] = "political",
["ipv4Ranges"] = {
"156.33.0.0/16",
},
["ipv6Ranges"] = {
"2620:0:8a0::/48",
"2600:803:618::/48",
}
},
},
["entity-ids"] = {
"ussenate",
},
},
}
</syntaxhighlight>
=== One match, JSON output ===
Query:
Query:
<syntaxhighlight lang="lua">
querySensitiveIPs{
format = 'json',
test = {'156.33.5.76'}
}
</syntaxhighlight>
Result:
<syntaxhighlight lang="json">
{
"sensitiveips":{
"matches":[
{
"type": "ip",
"ip": "156.33.5.76",
"ip-version": "IPv4",
"matches-range": "156.33.0.0/16",
"entity-id": "ussenate"
}
],
"matched-ranges": {
"156.33.0.0/16": {
"range": "156.33.0.0/16",
"ip-version": "IPv4",
"entity-id": "ussenate"
}
},
"entities": {
"ussenate": {
"id": "ussenate",
"name": "United States Senate",
"description": "the [[United States Senate]]",
"reason": "political",
"ipv6Ranges": [
"2620:0:8a0::/48",
"2600:803:618::/48"
],
"ipv4Ranges": [
"156.33.0.0/16"
]
}
},
"entity-ids": [
"ussenate"
]
}
}
</syntaxhighlight>
=== Entity IDs ===
<syntaxhighlight lang="lua">
querySensitiveIPs{
format = 'json',
entities = {'usdhs', 'usdoj'}
}
</syntaxhighlight>
Result:
<syntaxhighlight lang="json">
{
"sensitiveips": {
"entities": {
"usdoj": {
"id": "usdoj",
"name": "United States Department of Justice",
"description": "the [[United States Department of Justice]]",
"reason": "political",
"ipv4Ranges": [
"149.101.0.0/16"
]
},
"usdhs": {
"id": "usdhs",
"name": "United States Department of Homeland Security",
"description": "the [[United States Department of Homeland Security]]",
"reason": "political",
"ipv4Ranges": [
"65.165.132.0/24",
"204.248.24.0/24",
"216.81.80.0/20"
]
}
},
"entity-ids": [
"usdoj",
"usdhs"
]
}
}
</syntaxhighlight>
=== Invalid IP error ===
Query:
<syntaxhighlight lang="lua">
querySensitiveIPs{
test = {'foo'}
}
</syntaxhighlight>
Result:
<syntaxhighlight lang="lua">
{
["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",
}
}
</syntaxhighlight>
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
| |||