Editing Module:Sensitive IP addresses/API/doc (section)

== Results ==

By default, the query function returns a Lua table, but it can return a JSON object if the <code>format</code> option is set to <code>json</code>. 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 <code>sensitiveips</code> and contains the query results.

<syntaxhighlight lang="json">
{
    "sensitiveips": {
        [query results]
    }       
}
</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:

<syntaxhighlight lang="json">
{
    "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>

=== Sensitive IPs object ===

If the query was successful, the <code>sensitiveips</code> child object will be present and can contain the following objects and arrays:
* <code>matches</code> - an array of [[#IP address objects|IP address objects]] or [[#IP range objects|IP range objects]], where the corresponding IP address or IP range string was specified in the <code>test</code> 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.
* <code>matched-ranges</code> - 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 <code>test</code> query option. If no IPs or ranges were tested for, or if no matches were found, this object will not be present.
* <code>entities</code> - an object with entity IDs as keys, and [[#Entity objects|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, <code>ushr</code> 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 <code>test</code> query option, or if their entity ID is specified in the <code>entities</code> query option.
* <code>entity-ids</code> - 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 <code>entities</code> result object. This array can be useful for outputting the IDs in the same order that they were defined in the list.

=== IP address objects ===

An IP address object represents a single IPv4 or IPv6 address that matches a sensitive IP range. IP address objects contain the following fields:
* <code>ip</code> - the string representation of the IP address, e.g. "1.2.3.4" or "2001:d8::ffff:ab:cdef".
* <code>type</code> - the string "ip" (used to differentiate between IP address objects and IP range objects).
* <code>ip-version</code> - the version of the IP protocol the address uses. This is either "IPv4" or "IPv6".
* <code>matches-range</code> - the sensitive IP range that the address matches, in CIDR notation.
* <code>entity-id</code> - the entity ID of the entity that owns the sensitive IP range that the address matches.

=== IP range objects ===

An IP range object represents an IPv4 or IPv6 range that overlaps with a sensitive IP range. IP range objects contain the following fields:
* <code>range</code> - the CIDR string representation of the range, e.g. "1.2.3.0/24" or "2001:d8::ffff:ab:0/16".
* <code>type</code> - the string "range" (used to differentiate between IP range objects and IP address objects).
* <code>ip-version</code> - the version of the IP protocol the range uses. This is either "IPv4" or "IPv6".
* <code>matches-range</code> - the sensitive IP range that the tested range overlaps, in CIDR notation.
* <code>entity-id</code> - the entity ID of the entity that owns the sensitive IP range that the tested range overlaps.

=== Entity objects ===

An entity object represents a country or organization that has IP ranges which Wikipedia considers sensitive. Entity objects may contain the following fields:
* <code>id</code> - the entity ID. This is a unique string used to identify the entity. This field is always present.
* <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.