Module:Sensitive IP addresses/API/doc: Difference between revisions

Revision as of 23:59, 24 August 2016

Revision as of 01:35, 25 August 2016

Line 1:

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 actionAction API]] such as JavaScript gadgets and bots.

== Usage ==

Line 30:

* <code>entities</code> - 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, <code>ushr</code> is the ID for the [[United States House of Representatives]]. If the special ID <code>all</code> is contained in the array, information about all entities will be included in the result.

* <code>format</code> - the format to return results in. Use <code>json</code> to return a [[JSON]]-formatted string, and use <code>lua</code> 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 <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.

<source lang="json">

{

"sensitiveips": {

[query results]

}

}

</source>

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:

<source 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"

}

}

</source>

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |