11.5 Service Items: REST API

11.5.1 Server-Side Support: REST API

■ Management of License Information within Servers

When managing license information per user within servers, you must create entries so that users can be uniquely identified. You must also include environment information such as the development environment, Lotcheck environment, or production environment in the entries you create. This is to prevent work done in the development environment from affecting users in the production environment.

Note:

You can get environment information by decoding the service token. See the CTR Account System Developer's Guide for details.

Nintendo recommends using the principal ID from the Nintendo Network ID when creating entries.

 

11.5.1.1 Creating Entries within Servers

Guideline Item

You must create entries that allow users to be identified uniquely on servers, and include environment information such as the development, Lotcheck, or production environment in the entries.

Software to Be Tested

Applications that meet all of the following conditions:

  • The application supports service items that use the eShop REST API.
  • Applications that need to distinguish between users on the server side for purposes such as user management.
Test Method

Check the source code.

Pass/Fail Determination

Passes if the inclusion of environment information allows users to be uniquely identified.

11.5.2 Using Service Items: REST API

■ Display of Amount of Time/Uses on the Final Purchase Screen for Subscription Tickets and Consumable Tickets

If your application allows purchase of subscription tickets and/or consumable tickets, failure to display the amount of time/uses remaining for that item on the final purchase screen could violate European law. In titles for the European market, you must always configure the PurchaseInfo structure and pass it to the nn::ec::CTR::ShowPurchaseConfirmationDialog function (or the nn::ec::CTR::PurchaseConfirmationApplet::RequestShowDialog function in CTR-SDK versions earlier than 11.4.0) so that the amount of time/uses remaining is displayed within the final purchase screen on the EC applet. If you use consumable tickets to implement a subscription service that has an expiration element, you must display the amount of time remaining instead of uses.

11.5.2.1 Display of Amount of Time/Uses on the Final Purchase Screen

Guideline Item

Applications that allow purchase of subscription tickets and/or consumable tickets must display the amount of time/uses of the items the user is purchasing on the final purchase screen of the purchase confirmation screen applet.

Software to Be Tested

Applications that meet all of the following conditions:

  • The application uses service items via the eShop REST API.
  • Applications for the Europe market.
Test Method

Purchase a subscription ticket or consumable ticket, and check the final purchase screen of the purchase confirmation screen applet.

Pass/Fail Determination

Passes if the amount of time/uses for the item you are purchasing is displayed.

11.5.3 Displaying Errors

■ Displaying Errors

If execution of an eShop REST API function did not complete successfully for some reason, error information is returned as the response. Error handling is essentially left up to the independent servers' implementations, but the following error codes must be displayed on the client side by the client application.

  • 030-3550
  • 030-3551 (Occurs only in Americas)
  • 030-3552 (Occurs only in Americas)
  • 030-3698

Use the error/EULA applet to display eShop REST API errors. To display an error, call the error/EULA applet and specify the error code of the error to display.

If an error occurs that is not listed above, display it as necessary in line with your application's specifications. In such cases, displaying the error code and the prescribed error message exactly as written is optional. It is acceptable to not display them, or to modify the prescribed error message.

11.5.3.1 Displaying Errors for the eShop REST API

Guideline Item

If eShop REST API errors occur that must be displayed on the client side, the application must use the error/EULA applet to display them.

Software to Be Tested
Applications that use service items via the eShop REST API.
Test Method

Check the source code.

Pass/Fail Determination

Passes if the client application displays the following errors via the error/EULA applet when they occur:

  • 030-3550
  • 030-3551 (Occurs only in Americas)
  • 030-3552 (Occurs only in Americas)
  • 030-3698

11.5.4 Checking Whether a System Update is Required

When you use the eShop REST API, the application uses a dedicated applet called the purchase confirmation screen applet to display the item purchase screens.

The purchase confirmation screen applet does not check to see whether or not a system update is required. Because there is a chance that the display of the purchase confirmation screen applet itself will be changed by a system update, when using the eShop REST API, you must check on the application side if a system update is required before you call the purchase confirmation screen applet. If a system update is required, specify error 009-1000 directly to the error/EULA applet to display the error. Likewise, do not display the purchase confirmation screen applet if a system update is required. You can use the nn::ec::CTR::NeedsSystemUpdate function to check whether a system update is required.

There is no need to check whether a system update is required every time the user makes a purchase, but if you log out of the independent server, you must call the nn::ec::CTR::NeedsSystemUpdate function again before the next time you call the purchase confirmation screen applet.

11.5.4.1 Checking for System Updates

Guideline Item

The application must check to see if a system update is required before calling the purchase confirmation screen applet, and must not launch the purchase confirmation screen applet if a system update is required. If the application logs out of the independent server, the application must check for a system update again before the next time it calls the purchase confirmation screen applet.

Software to Be Tested

Applications that use service items via the eShop REST API.

Test Method
  1. Prepare a system by applying a SystemUpdater that supports the CTR-SDK 10.1.x series or later.
  2. Launch the DevMenu, and delete the program displayed as "00108   Dummy data title".
  3. Launch the application and progress to a scene where it is possible to purchase an item with the eShop REST API.
  4. Log out of the independent server and check the source code to confirm the application's behavior up until it next calls the purchase confirmation screen applet.

After you complete this test, you can perform a system update from System Settings to return the system to a state where system update is not required. To perform the system update, you must set the DNS to DEV3.

Pass/Fail Determination

Passes if all of the following conditions are met.

  • In step 3, the purchase confirmation screen applet does not launch, and instead error 009-1000 is displayed.
  • In step 4, the application calls the nn::ec::CTR::NeedsSystemUpdate function sometime after logging out of the independent server but before launching the purchase confirmation screen applet.

 


CONFIDENTIAL