12.1. Using the Web API

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.

12.1.1. Purpose of the Web API

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.

It can be used for the following purposes.
  • Tabulate the ratings in a data store once per day and display them on a webpage.
  • Move the data posted in a data store to a management server once per day.
  • Delete rating data older than a specific period of time.
It cannot be used for the following purposes.
  • Have the client make a request to the independent server to get specific data, and have the independent server call the web API based on that request.
  • Replace all data in a data store at a specific time. (This would require more than one access per minute.)
  • Send requests to the web API based on user requests in a web service.

Contact Nintendo if you are unsure which case your application falls under.

12.1.2. Accessing the Web API

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.

12.1.3. Resource URL Path

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

12.1.4. Request

12.1.4.1. Request Method

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.

12.1.4.2. Parameters and Request Body

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>
    

12.1.4.2.1. Multiple Values

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>
    

12.1.5. Response

12.1.5.1. Status Code

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.

12.1.5.2. Content

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>

12.1.6. Handling Special Request and Response Data

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.

12.1.6.1. Base64 Encoding

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.

  • Use "=" for padding (when required).
  • Do not use newline characters.

The rules for making data URL-safe are as follows.

  • Use "-" instead of "+"
  • Use "_" instead of "/"

Conversion Examples:

  • Encode "NEX WebAPI"
    • NG: TkVYIFdlYkFQSQ (No padding)
    • OK: TkVYIFdlYkFQSQ==
  • Encode a byte array containing 0x3c, 0x3d, 0x3e, and 0x3f.
    • NG: PD0+Pw (Not URL-safe and no padding)
    • NG: PD0+Pw== (Not URL-safe)
    • NG: PD0-Pw (No padding)
    • OK: PD0-Pw==

12.1.7. Requests via the Web API Gateway

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 and NEX3_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.

12.1.7.1. Sample Request via the Web API Gateway

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