Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #4121

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #4121

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions clients/sellingpartner-api-aa-javascript/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
This library is to help SP-API developers to create an app in JavaScript on Node.js easier than calling HTTP endpoints directly. This library comes with the following features.
1. Login with Amazon (LWA) helper that does OAuth token refresh flow.
2. This library takes care of HTTP communication with SP-API endpoints with a help of [superagent](https://www.npmjs.com/package/superagent), so you can call SP-API by just calling a right method of library that corresponds to SP-API operation.
3. Calling SP-API requires non-standard `x-amz-access-token` HTTP request header in request. The SDK generated by this library supports to include this header with token value you specify.
4. SP-API operaitons to handle restricted data are categorized as ["Restricted Operations"](https://developer-docs.amazon.com/sp-api/lang-ja_JP/docs/tokens-api-use-case-guide#restricted-operations), which requires ["Restricted Data Token" (RDT)](https://developer-docs.amazon.com/sp-api/lang-ja_JP/docs/authorization-with-the-restricted-data-token) instead of access token for tighter security. Calling restricted operation involves two seprate steps, one of wihch is calling Tokens API to retrieve RDT and the other of which is calling protected operation with RDT. This library helps to compbine these two steps into single library call.
3. Calling SP-API requires non-standard `x-amz-access-token` HTTP request header in the request. The SDK generated by this library supports to include this header with the token value you specify.
4. SP-API operations to handle restricted data are categorized as ["Restricted Operations"](https://developer-docs.amazon.com/sp-api/lang-ja_JP/docs/tokens-api-use-case-guide#restricted-operations), which requires ["Restricted Data Token" (RDT)](https://developer-docs.amazon.com/sp-api/lang-ja_JP/docs/authorization-with-the-restricted-data-token) instead of access token for tighter security. Calling restricted operation involves two separate steps, one of which is calling Tokens API to retrieve RDT and the other of which is calling protected operation with RDT. This library helps to combine these two steps into a single library call.

## Installation and Generating SDK
Please note this library doesn't include SDK. You need to generate SDK with the template and script files included in this library.
Expand All @@ -17,7 +17,7 @@ Please note this library doesn't include SDK. You need to generate SDK with the

__CAUTION__: Please be aware that there are two major known issues with the latest JavaScript client library.
1. If you use swagger-codegen-cli newer than 2.4.29 (such as 2.4.30 or 3.x), there is a known compatibility issue with SP-API models that makes generating SDK fail. We recommend that you use swagger-codegen-cli-2.4.29 specifically.
2. Swagger codegen tool fails to generate SDK for "Merchant Fulfillment V0 API." For workaround, you need to modify a part of the API model file "merchantFulfillmentV0.json"
2. Swagger codegen tool fails to generate SDK for "Merchant Fulfillment V0 API." For a workaround, you need to modify a part of the API model file "merchantFulfillmentV0.json"

### Download swagger-codegen-cli JAR file
We use `swagger-codegen-cli` executable JAR file. You can download it by the following command.
Expand All @@ -41,14 +41,14 @@ You will find `models` directory and `sdk` directory under the package root.<br>
* `models`: directory contains API models cloned from SP-API GitHub.
* `sdk`: directory contains generated JavaScript SDK.

### Modify Merchant Fulfillment API model file to avoid error during SDK generation
If you want to call Merchant Fulfillment API with the generated SDK, you need to follow this instruction. There is an fatal known issue in generating Merchant Fulfillment API library. If downloading API models is successful, you should be able to find `merchantFulfillmentV0.json` file In `<package root>/models/merchant-fulfillment-api-model` directory. Open this file with an editor and find the following part.
### Modify Merchant Fulfillment API model file to avoid errors during SDK generation
If you want to call Merchant Fulfillment API with the generated SDK, you need to follow this instruction. There is a fatal known issue in generating Merchant Fulfillment API library. If downloading API models is successful, you should be able to find `merchantFulfillmentV0.json` file In `<package root>/models/merchant-fulfillment-api-model` directory. Open this file with an editor and find the following part.
```
"AvailableFormatOptionsForLabel": {
"$ref": "#/definitions/AvailableFormatOptionsForLabelList"
},
```
Since this part causes a fatal error in SDK generation for JavaScript, please replace this part with the following snipet.
Since this part causes a fatal error in SDK generation for JavaScript, please replace this part with the following snippet.
```
"AvailableFormatOptionsForLabel": {
"type": "array",
Expand All @@ -67,7 +67,7 @@ Found <package root>/models already exists. Would you like to delete all the fil
With the correct modification in `merchantFulfillmentV0.json`, you should be able to find generated SDK for Merchant Fulfillment API.

### How to run tests
This library contains a sample programs in `sample_node_app` directory under the packagte root.<br>In order to run the program, you need to have LWA credential information saved in the file and name it `app.config.mjs` and put it `<package root>/src` directory. Because __client secret__ and __refresh token__ shouldn't be exposed, you must make sure that you don't commit this file to the repository.
This library contains sample programs in `sample_node_app` directory under the package root.<br>In order to run the program, you need to have LWA credential information saved in the file and name it `app.config.mjs` and put it `<package root>/src` directory. Because __client secret__ and __refresh token__ shouldn't be exposed, you must make sure that you don't commit this file to the repository.
```javascript
export const AppConfig = {
lwaClientId: "< LWA client ID >",
Expand Down Expand Up @@ -101,7 +101,7 @@ ordersApiClient.enableAutoRetrievalRestrictedDataToken("<client ID>",
const ordersApi = new OrdersV0Api(ordersApiClient);
const order = await ordersApi.getOrder("<order ID to retrieve>");
```
### Calling SP-API with access token
### Calling SP-API with the access token
In case you manage LWA token refresh flow, you can explicitly use the access token you got yourself for your SP-API call as follows.
```javascript
import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js';
Expand All @@ -112,10 +112,10 @@ sellerApiClient.applyXAmzAccessTokenToRequest("<access token you retrieve yourse
const participations = await sellerApi.getMarketplaceParticipations();
```
### LWA Token refresh helper
The following code shows how to use `LwaAuthClient` to execute token refresh flow.
The following code shows how to use `LwaAuthClient` to execute the token refresh flow.
```javascript
import { LwaAuthClient } from "<path to helper/LwaAuthClient.mjs>";

const lwaClient = new LwaAuthClient("<client ID>", "<client secret>", "<refresh token>");
const accessToken = await lwaClient.getAccessToken();
```
```