Platform Technology-SPI Service Access Document


What is SPI

  • Service Provider Interface
    • API: The platform provides the interface and implements it, you call it
    • SPI: The platform provides standards and you implement them. There can be multiple implementation methods

image

##SPI settlement process

image

What you need to do is the work in the third box.

Application Business Scenario

First of all, you must have an APP with the "Three-Party Application" label. Click

here to apply.

After the application is successful, enter the application's console and you will see the "API Service Provider" menu

image

Note: You can see the current application in the overview AppKey and AppSecret.

    AppKey: has two functions.
    • After the scene owner (the person who introduces you to access SPI) binds this AppKey to the scene, you will have the access to a certain scene. Development rights, you can see this scene on this page.
    • SPI caller needs to fill in this AppKey in TargetAppkey to transfer to the service you implemented;
    • AppSecret: Open Platform (TOP) when calling the service you implemented , the message will be signed (see signature-related chapters for details). This key is used when signing. You need to use this key for signature verification.
Let’s take the “weather” scene as an example. When the scene owner binds this scene to your AppKey, you can see the "weather" scene on this page.

The scene status at this time is "under development". In addition to this status, the scene also has several statuses such as "online and running" and "upgrading".

    "Under development" to "Online and running": The application for release is approved;
  • "Online and running" to "Upgrading": After clicking to enter the upgrade, for any API click to upgrade version. Clicking "Cancel Upgrade" or applying for release and passing the review will return to "Online and Running".

image

#After entering the scene, you can see all the APIs to be implemented in the scene, as shown in the figure below.

image

Meanwhile, next to the scene is its current state.

Read the document

Be sure to read the document carefully before developing. After clicking "Develop Documentation", you can see the picture below.

image

Please develop strictly in accordance with the documentation, pay specific attention to:

  • Request method: POST or GET;
  • Request encoding: UTF-8 or GBK;
  • Public request parameters, business request parameters and response parameters must be completely consistent with the document. For the return value, please refer to the return example;
  • Exception handling: Return the specified fields according to the specifications here, and the open platform will use this to determine whether your return is successful or failed;
  • Request example: You can use here Replace your parameters with the example to test the service you implemented. Note that this method is very useful for troubleshooting errors.

Service Development

The completion of service development is a process of independent research and development by you. You only need to strictly follow the protocol in the document to develop. There are no special requirements for development language and deployment environment.

For security, we strongly recommend that your service verify the signature and verify the requester's IP. In order to facilitate your development, we have SDK provided to you. Please see the picture below for the SDK download page.

image

Signature verification

Required! The purpose of signature verification is to prevent hackers from maliciously calling your services and ensure that the source of service initiation is the Alibaba platform.

Currently, the signature verification method only provides three versions of SDK: JAVA, PHP, and .NET. Other languages ​​need to be implemented by yourself.

The signature method generation rules are:

  • Save the query parameters and header parameters into a map for later use. For convenience of explanation, this map is named params. Note: The sign parameter in query cannot be put into params;
  • If the type in the body is form-data, put all parameters in the body except files into params. For some technical reasons, files passed through form-data are not signed;
  • If the type in the body is json or xml, temporarily save the body for later use. For convenience of explanation, this content is named body;
  • Sort the params in alphabetical order of key, then traverse it, and form a string according to key1 value2 key2 value2..., for convenience of explanation , which is later called the signature string. If value is empty, use "" instead. If the body is not empty, add all the contents of the body to the end of the signature string;
  • Add secret to the beginning and end of the signature string. This secret is obtained when SP applies for an application. At this point, the signature string is generated;
  • perform md5 and hex on the signature string, and finally get sign. To summarize, the formula for generating sign is:
    hex(md5(secret sorted(header_params url_params form_params) body) secret)
  • Finally, compare the generated sign with the sign obtained from the query, The correctness of the signature can be verified.

The signature verification sample code is as follows:

import java.io.IOException;
 
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
 
import com.taobao.api.internal.spi.CheckResult;
import com.taobao.api.internal.spi.SpiUtils;
 
public class TestHttpServlet extends HttpServlet {
 
    private static final long serialVersionUID = -7841738585932624564L;
 
    protected void doPost(HttpServletRequest req, HttpServletResponse rsp) throws ServletException, IOException {
        CheckResult result = SpiUtils.checkSign(req, "fb821bc8785f2409a942eec601e6071d");
        System.out.println(result.isSuccess());
        System.out.println(result.getRequestBody());
    }
 
}
Note: The URL parameter encoding character set in the HTTP request and the character set when converting strings to byte streams for MD5 digest must be consistent, otherwise the signature containing Chinese parameters will be inconsistent with TOP.

IP source verification

Required! Prevent hackers from intercepting HTTP requests initiated by the open platform and taking them to other places for replay attacks.

The egress IP segment of Taobao Open Platform Gateway can be obtained through taobao.top.ipout.get. It is updated irregularly and needs to call the API regularly to obtain the latest data.

IP source verification sample code is as follows:

public class TestHttpServlet extends HttpServlet {

private static final long serialVersionUID = -7841738585932624564L;

protected void doPost(HttpServletRequest req, HttpServletResponse rsp) throws ServletException, IOException {
// The latest IP segment list can be obtained through taobao.top.ipout.get
List<String> ipList = new ArrayList<String>();
ipList.add("140.205.144.0/24");
ipList.add("140.205.145.0/24");
ipList.add("140.205.40.0 /24");
ipList.add("140.205.39.0/24");
ipList.add("140.205.51.0/24");
ipList.add("140.205.56.0/24 ");
Boolean Issuccess = Spiutils.Checkremoteip (REQ, iPlist);
if (! Issuccess) {
RSP.getWriter (). Write (" Access Denied ");
RS p.getWriter ().flush();
}
}

}

Another way is to configure IP access rules on the HTTP Server. For example, configuring Nginx to only allow TOP IPs to access the /taobao directory:

##location /taobao {
allow 140.205.144.0/24;
allow 140.205.145.0/24;
allow 140.205.39.0/24;
allow 140.205.40.0/24;
allow 140.205.51.0 /24 ;
allow 140.205.56.0/24;
deny all;
}

Configuration Service

Click "Develop and Test" to enter the page shown below:

image

There are two address input boxes here:

  • Test environment address: This address is for testing only. This is discussed in detail in the next section.
  • Online environment address: When this SPI service is released and online, the address called by the online environment is this URL.

Test Service

There are two places to initiate testing,

1) SPI test tool. Click "Enter Test" on this page to enter this tool. See the image below:

image

#By default, there is only one test case: smoke test. This test is just an HTTP request assembled by the SPI test tool according to the protocol and sent to the test environment address.

If you want to add test cases, please contact the person in charge of the SPI platform.

After the test is completed, you can view all parameters of this HTTP request in the test details. You should especially pay attention to the content in the "response information", which may be a preliminary check whether your service is normal.

image

2) API testing tool daily, sandbox environment: The test here is to test the complete process of SPI, which is an essential step before your service is released online. , only if this step is passed can it be proved that your service is running normally.

Call a TOP API, and TOP will route the request to your test environment address. You need to tell the API caller the AppKey, and the latter will add "10" in front of it and fill in the parameter targetAppkey.

You can also be a guest API caller yourself. The prerequisite is that the scene owner first adds this API to the sandbox, and then you apply for permission to call this API. It should be noted that the targetAppkey for sandbox testing is also your appkey with "10" in front of it; also, the signing key is the sandbox key.

You can go to here to read the documentation for how to call the API.

Application for Release

After the test is completed, click "Complete Test" to return to the scene list page in Figure 5. If you think the newly configured URL can be published to take effect, click "Apply for publication". If this scenario is configured as "Requires Review", it will need to be reviewed by the person in charge of the SPI platform before it can be released and take effect; otherwise, it can take effect immediately.

FAQ

  • There is no FAQ about this document
←
→