Interface Description

Before releasing a SaaS product to KooGallery, develop a production interface on your server by referring to this access guide.

The following table lists the SaaS 2.0 interface specifications.

Scenario	SaaS
Scenario	One-Time Payment	Yearly/Monthly	Pay-per-Use
Creating an instance	Mandatory	Mandatory	Mandatory
Querying instance information	Mandatory	Mandatory	Mandatory
Updating an instance	N/A	Mandatory	Mandatory
Updating the instance status	N/A	Mandatory	Mandatory
Releasing an instance	Mandatory	Mandatory	Mandatory
Upgrading an instance	N/A	Optional	N/A
Verifying a change upon renewal	N/A	Optional	N/A

When releasing a product, develop interfaces based on the delivery method and billing mode as listed in the preceding table.

Mandatory: Development and debugging are mandatory.
N/A: No development and debugging are required.
Optional: For instance upgrade and verification of changes upon renewal, development and debugging are required only when a product allows specification adjustments (downgrades/upgrades) or capacity scaling (in/out). Ignore them for other cases.

SaaS 2.0 Instance Dialing Test Rules

After SaaS product release, KooGallery conducts interface address dialing tests every morning and afternoon to monitor the availability for order placement. If a dialing test fails, the system sends a notification to the email address or mobile number bound to your account or as a direct message. Rectify the interface promptly. The following table lists the dialing test rules.

Product Status	Dialing Test
On sale	Required
Discontinued	Skipped
Withdrawn from KooGallery	Skipped

If the dialing test of an interface fails for five consecutive days, the KooGallery operations manager freezes the product transaction and hides the product from customers. According to the Huawei Cloud KooGallery Partner Product Seller Agreement, if the fault is not rectified in time, KooGallery has the right to remove the product from the catalog.

Interface Calling Scenario (Order Placement)

Instance creation: A customer purchases and pays for a product.
1. KooGallery calls the instance creation interface to ask you to create an instance based on the order ID.
2. After receiving the request, your system calls the KooGallery API for querying an order to obtain the subscription information and subscribe to the instance.
3. KooGallery calls the instance query interface to obtain instance information.

Instance query: A customer queries information about an instance (instanceId).
1. After obtaining the instance ID (instanceId) returned by the instance creation interface, KooGallery continuously calls the instance query interface until you successfully return the instance information.
2. When a customer queries resource information in KooGallery, KooGallery synchronously calls the instance query interface and returns the information.
Instance update: A customer changes trial use to commercial use, renews resources, cancels renewals, or changes specifications during renewal.
KooGallery calls the instance update interface to notify your system of the resource expiration time. Your system performs the corresponding action and returns the execution result to KooGallery.
Instance status update: If an instance of a customer expires or the customer violates regulations, the instance will be frozen. After the instance is renewed or the violation is canceled, the instance will be unfrozen.
KooGallery calls the instance status update interface to ask your system to freeze or unfreeze the corresponding resource and return the execution result to KooGallery.

When a purchased product expires, the retention period starts. The retention period varies with the customer tier and can be up to 15 days long. During the retention period, the product is frozen and cannot be used. The customer can continue using the product after renewal. Therefore, you need to set a retention period to no less than 15 days for your SaaS products and retain customer data during the retention period.

Instance release: A customer releases an instance of a purchased product (in scenarios such as no renewal upon expiration and unsubscription).
1. KooGallery calls the instance release interface to ask your system to release the corresponding resource and return the execution result to KooGallery.
Instance upgrade: A customer upgrades purchased resources and pays for the upgrade order.
1. KooGallery calls the instance upgrade interface to ask your system to upgrade the corresponding resource.
2. Your system calls the KooGallery API for querying an order to obtain the upgrade information, upgrades the instance, and returns the execution result to KooGallery.
Verification of changes upon renewal: When a customer requests to upgrade or downgrade resource specifications or scale in or scale out resources during renewal, KooGallery calls this interface to check whether your server supports such changes.

For details about the process, see Upgrade and Billing Rules.

Interface Failure Scenarios and Retry Mechanism

If an interface fails to respond, the system sends an email to the email address bound to your KooGallery account. You can query the exception information on the Service Interface Messages page of the Seller Console. Handle the exceptions as soon as possible to avoid unsubscription due to order failure.

When the instance creation interface fails to be called, KooGallery retries for 3 hours. You can click Restart in the Operation column on the right of the order on the Service Interface Messages page to retry calling. If the interface exception persists after 3 hours, the system determines that the order fails and cancels the order.
When the instance update interface fails to be called, KooGallery retries calling in the following scenarios:
1. For renewals, changes from trials to commercial use, and renewal cancellation, KooGallery retries for an hour. You can query the exception information on the Service Interface Messages page. After rectifying the exception, click Restart in the Operation column on the right of the order on the Service Interface Messages page to retry calling.
2. For changes upon renewal, KooGallery retries for 3 hours. You can click Restart in the Operation column on the right of the order on the Service Interface Messages page to retry calling. If the interface exception persists after 3 hours, the system determines that the order fails and cancels the order.
When the instance status update interface fails to be called, KooGallery retries for an hour. You can query the exception information on the Service Interface Messages page. After rectifying the exception, click Restart in the Operation column on the right of the order on the Service Interface Messages page to retry calling.
When the instance upgrade interface fails to be called, KooGallery retries for 3 hours. You can click Restart in the Operation column on the right of the order on the Service Interface Messages page to retry calling. If the interface exception persists after 3 hours, the system determines that the order fails and cancels the order.
- If an interface fails to respond, an email, SMS message, or direct message will be sent to you. Check the email address and mobile number bound to your account and the Message Center on Huawei Cloud.
- If more than five orders of a product failed in a month due to interface failures or an interface fails the dialing test for five consecutive days, KooGallery will remove the product from the catalog.
- If an order is automatically canceled due to an interface failure, contact the customer at the earliest to handle the problem. If a customer can still use expired resources due to an interface failure, you shall bear the resource loss incurred.