This section describes how to use the web API and things to note when using it.
Warning
This is a beta version of the documentation. Specifications are subject to change in future versions.
The NEX Web API can be used for data management on the game server. The web API can be used for operations such as tabulating data and periodically posting and deleting data. In addition, because the API is provided for data management, you should only send one request per minute for each title. The web API cannot be used for purposes such as executing client requests and frequent updating.
Contact Nintendo if you are unsure which case your application falls under.
To use the web API, you must apply to use a web service on OMAS. Once your application is approved, you will be able to generate the OAuth 2.0 access token required to use the web API. For more information on the procedure, see the Usage page on the OMAS site.
The resource URL path of the API is generally structured as follows.
/nex/{moduleName}/v{version}/{apiPath}
Element Details moduleName Module name version API version apiPath Path of API function
For example, to search using version 2 of the data store API, you would use the following path.
/nex/datastore/v2/search
However, you do not specify the version in certain API functions, such as those used for getting the version.
/nex/datastore/version
The request method is either GET, POST, PUT, or DELETE. The method to use depends on the API function, as do the ways request parameters are passed and formatted.
To pass the parameters, in general, use the query string with the GET method and use the request body in a XML format with the POST and PUT methods. When making a request using the XML format, set the header to Content-type:text/xml
. Parameters are not used with DELETE.
Request Examples:
Get the metadata, including tags, for data ID 10 in the data store. (GET)
GET /nex/datastore/v2/metainfo/10?response=tag HTTP/1.1
Change the name of data ID 10 to "new name" in the data store. (PUT)
PUT /nex/datastore/v2/metainfo/10 HTTP/1.1
<change>
<name>new name</name>
</change>
Some of the API functions accept multiple values. You generally use commas to delimit multiple values when using GET, and use multiple XML elements when using POST and PUT.
Request Examples:
Get the metadata for data IDs 10, 20, and 30 in the data store.
GET /nex/datastore/v2/metainfo?data_ids=10,20,30 HTTP/1.1
Change the tags of data ID 10 to "tag1" and "tag2" in the data store. (PUT)
PUT /nex/datastore/v2/metainfo/10 HTTP/1.1
<change>
<tags>
<tag>dGFnMQ==</tag>
<tag>dGFnMg==</tag>
</tags>
<param>
<data_id>10</data_id>
</param>
</change>
The execution result of a request generally uses one of the following status codes.
Status Code Details 200 Function completed successfully. 400 Invalid request parameter. 404 Path does not exist. 500 Internal error.
Detailed execution results and content are returned in XML format. When the API function succeeds, the content is as follows.
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<module>
<!-- Response content -->
</module>
</nex>
The <module> element above represents the module name. For example, the data store module would appear as follows.
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<datastore>
<!-- Response content -->
</datastore>
</nex>
If an error occurs, the following content is returned.
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<errors>
<error>
<errorcode><!-- Error code --></errorcode>
<message><!-- Error message --></message>
</error>
</errors>
</nex>
Some API functions require the data to be processed before it is passed as an argument. The resulting data is also returned in the processed format.
When using Base64 encoding, use RFC 3548-based encoding. The encoded data must also be in a URL-safe format.
Note the following points when encoding in Base64.
The rules for making data URL-safe are as follows.
Conversion Examples:
0x3c
, 0x3d
, 0x3e
, and 0x3f
.To use the web API, you must access the game server through the web API gateway. Use the following URL to send a request to the game server through the web API gateway.
https://nexapi.app.nintendo.net/{GameServerID}/{Environment}/nex/
Element Details GameServerID Specifies the game server ID to be displayed in OMAS. The leading " 0x
" is not needed.Environment Specifies the development environment or the production environment. Specify NEX3_
DEV
for the development environment andNEX3_
LIVEMM
for the production environment.
An access token is required to issue a request. There are two types of access tokens: an unlimited token that does not expire, and a token that is limited to 1 hour. When using a token with a time limit, check the expiration date and, if necessary, use a refresh token to refresh the access token before use. From a security standpoint, We recommend using and refreshing the one-hour token.
Warning
When using an unlimited token, create a dedicated account for the game title and use the access token obtained with that account instead of an access token obtained with a developer account. Access tokens inherit the privileges of the user that issues them. If the user who issued the token loses those privileges due to retirement, transfer, or other reason, the access token becomes invalid.
This is a sample of a web API request through the web API gateway under the following conditions.
Element Details GameServerID 0x1234abcd Environment NEX3_ DEV Access Token abcd123456 Function Get metadata for data ID 123456
.
To make a request with these conditions, execute the following request.
GET https://nexapi.app.nintendo.net/1234abcd/NEX3_DEV/nex/datastore/v2/metainfo/123456 Authorization: OAuth abcd123456
To do this with cURL, use the following command.
curl -H "Authorization: OAuth abcd123456" --proxy http://<proxy_address>:<proxy_port> https://nexapi.app.nintendo.net/1234abcd/NEX3_DEV/nex/datastore/v2/metainfo/123456
If the GET request succeeds, the following response is returned.
<?xml version="1.0" encoding="UTF-8"?> <nex> <datastore> <metainfos length="1"> <metainfo> <status>0</status> <referred_time>2013-01-01T00:00:00Z</referred_time> <referred_cnt>0</referred_cnt> <prev_version>0</prev_version> <data_type>0</data_type> <refer_data_id>0</refer_data_id> <data_id>xxxxxxx</data_id> <cur_version>x</cur_version> <access_permission> <type>0</type> <principal_ids length="0"/> </access_permission> <period>365</period> <update_permission> <type>3</type> <principal_ids length="0"/> </update_permission> <name>TDSS</name> <expire_time>2013-02-01T00:00:00Z</expire_time> <flag>34</flag> <read_lock_id>0</read_lock_id> <created_time>2013-01-01T00:00:00Z</created_time> <owner_id>xxxxxxxxxx</owner_id> <updated_time>2013-01-01T00:00:00Z</updated_time> <size>0</size> </metainfo> </metainfos> </datastore> </nex>
If an error occurs, the following response is returned.
<?xml version="1.0" encoding="UTF-8"?> <nex> <errors> <error> <errorcode>-1</errorcode> <message>qResult(0x80690004) Not found. Data Ids are [xxxxL]</message> </error> </errors> </nex>
If authentication fails due to an invalid access token or other reason, the following response is returned.
<?xml version="1.0"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value><int>403</int></value> </member> <member> <name>faultString</name> <value><string>Forbidden (Proxy)</string></value> </member> </struct> </value> </fault> </methodResponse>
CONFIDENTIAL