Skip to content

Commit 7e6d9ca

Browse files
jleversjlevers
committed
Improve authorization documentation
1 parent a12b2c2 commit 7e6d9ca

96 files changed

Lines changed: 1666 additions & 1453 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ The existing Walmart client libraries for PHP are either incomplete, outdated, o
5252
* [Configuration](#configuration)
5353
* [Using API classes](#using-api-classes)
5454
* [Using model classes](#using-model-classes)
55+
* [Authorization](#authorization)
56+
* [Basic auth](#basic-auth)
57+
* [Access token auth](#access-token-auth)
58+
* [Request signature auth](#request-signature-auth)
5559
* [Debug mode](#debug-mode)
5660
* [Supported API segments](#supported-api-segments)
5761
* [Marketplace](#marketplace)
@@ -113,13 +117,14 @@ The `Configuration` class is used to configure the client library. It takes thre
113117
- `$clientId`: Your Walmart Client ID
114118
- `$clientSecret`: Your Walmart Client Secret
115119
- `$options`: An optional associative array of additional configuration parameters. Valid options are:
116-
- `consumerId`: Your Walmart Consumer ID. Required if you are a Marketplace Seller selling in Canada, a Drop Ship Vendor, a Content Provider, or a Warehouse Supplier.
117-
- `privateKey`: Your Walmart private key. Required if you are a Marketplace Seller selling in Canada, a Drop Ship Vendor, a Content Provider, or a Warehouse Supplier.
118120
- `country`: The country you are selling in. One of `Country::US`, `Country::CA`, or `Country::MX`. Defaults to `US`.
119-
- `accessToken`: An instance of `Walmart\AccessToken`, containing an access token and its expiration time. If provided, this will be used instead of the client ID and secret to authenticate API calls, until the token expires. This is useful if you want to reuse an access token that you've already retrieved from Walmart.
121+
- `consumerId`: Your Walmart Consumer ID. Required if you are making requests to endpoints that use signature-based auth (see the [Authorization](#authorization) section)
122+
- `privateKey`: Your Walmart private key. Ditto the requirements for the `consumerId` option.
123+
- `accessToken`: An instance of `Walmart\AccessToken`, containing an access token and its expiration time. If provided, this will be used instead of the client ID and secret to authenticate API calls, until the token expires. This is useful if you want to reuse an access token that you've already retrieved from Walmart. More details on access token auth [below](#access-token-auth).
120124

121125
If you try to instantiate an instance of an API class that is not supported in the country you've specified, an exception will be thrown.
122126

127+
123128
### Using API classes
124129

125130
The API classes are divided into four categories: Marketplace, Drop Ship Vendor, Content Provider, and Warehouse Supplier. Each category has its own namespace, and each country has its own sub-namespace. For example, the Marketplace APIs for the US are located in the `Walmart\Apis\MP\US` namespace, and the Drop Ship Vendor APIs for Canada are located in the `Walmart\Apis\DSV\CA` namespace.
@@ -172,6 +177,20 @@ API methods often take model classes as parameters, and return them as API respo
172177
In order to represent the various data structures that the APIs ingest and return, this library uses model classes. Each model class represents a single data structure, and has a constructor that takes an associative array of data. The model class documentation is divided by API category, country, and API class. Documentation for each model class is nested inside the `docs/Models` folder corresponding to the model class's location in the `src/Models` folder. For instance, the response model for the Marketplace Authorization API's `getTokenDetail` method in the US is [`Walmart\Models\MP\US\Authorization\TokenDetailResponse`](https://github.com/highsidelabs/walmart-api-php/blob/main/src/Models/MP/US/Authentication/TokenDetailResponse.php), and the docs are at [`docs/Models/MP/US/Authorization/TokenDetailResponse.md`](https://github.com/highsidelabs/walmart-api-php/blob/main/docs/Models/MP/US/Authentication/TokenDetailResponse.md).
173178

174179

180+
### Authorization
181+
182+
Walmart uses three different forms of authentication for its APIs: basic auth, access tokens, and request signatures. This library handles all three automatically, so you shouldn't have to think about them much...but if you're curious about how it works, read on.
183+
184+
#### Basic auth
185+
This the standard, simplest form of authentication. It uses the Walmart client ID and client secret that are passed to the `Configuration` constructor in order to generate an authorization header value. It's also used to generate an access token if necessary, which is why these are the two required parameters for the `Configuration` constructor.
186+
187+
#### Access token auth
188+
For a lot of the Marketplace API, Walmart uses access token authentication. The access token is a short-lived token (15min) that is generated by Walmart with the client ID and client secret, and then used to authenticate API calls. This library automatically handles the generation and renewal of access tokens, so you don't have to worry about it. If you want to reuse an access token that you've already retrieved from Walmart, you can pass it to the `Configuration` constructor via the `accessToken` option.
189+
190+
#### Request signature auth
191+
For most of the rest of the APIs aside from the Marketplace API, Walmart uses request signature auth. This is just another value that is passed as a header, and it is generated using the request method and path, a timestamp, and your consumer ID and private key. If you're making requests that involve signature auth, you need to pass the `privateKey` and `consumerId` options to the `Configuration` constructor's options array.
192+
193+
175194
### Debug mode
176195

177196
To get debugging output when you make an API request, you can call `$config->setDebug()`. By default, debug output goes to `stdout` via `php://output`, but you can redirect it a file with `$config->setDebugFile('log/file/path.log')`.

‎docs/Apis/CP/US/FeedsApi.md‎

Lines changed: 28 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,6 @@ use Walmart\Walmart;
2727

2828
require_once __DIR__ . '/vendor/autoload.php';
2929

30-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
31-
'country' => 'US', // Default US if not set
32-
'privateKey' => 'PRIVATE_KEY',
33-
'consumerId' => 'CONSUMER_ID',
34-
]);
3530
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
3631
'country' => 'US', // Default US if not set
3732
'privateKey' => 'PRIVATE_KEY',
@@ -64,12 +59,15 @@ try {
6459

6560
### Authorization
6661

67-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
6862

69-
### HTTP request headers
7063

71-
- **Content-Type**: `multipart/form-data`
72-
- **Accept**: `application/xml`
64+
This endpoint requires the following authorization methods:
65+
66+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
67+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
68+
69+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
70+
7371

7472
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
7573
[[Back to Model list]](../../../Models/CP/US)
@@ -93,11 +91,6 @@ use Walmart\Walmart;
9391

9492
require_once __DIR__ . '/vendor/autoload.php';
9593

96-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
97-
'country' => 'US', // Default US if not set
98-
'privateKey' => 'PRIVATE_KEY',
99-
'consumerId' => 'CONSUMER_ID',
100-
]);
10194
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
10295
'country' => 'US', // Default US if not set
10396
'privateKey' => 'PRIVATE_KEY',
@@ -132,12 +125,15 @@ try {
132125

133126
### Authorization
134127

135-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
136128

137-
### HTTP request headers
138129

139-
- **Content-Type**: Not defined
140-
- **Accept**: `application/xml`
130+
This endpoint requires the following authorization methods:
131+
132+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
133+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
134+
135+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
136+
141137

142138
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
143139
[[Back to Model list]](../../../Models/CP/US)
@@ -161,11 +157,6 @@ use Walmart\Walmart;
161157

162158
require_once __DIR__ . '/vendor/autoload.php';
163159

164-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
165-
'country' => 'US', // Default US if not set
166-
'privateKey' => 'PRIVATE_KEY',
167-
'consumerId' => 'CONSUMER_ID',
168-
]);
169160
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
170161
'country' => 'US', // Default US if not set
171162
'privateKey' => 'PRIVATE_KEY',
@@ -202,12 +193,15 @@ try {
202193

203194
### Authorization
204195

205-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
206196

207-
### HTTP request headers
208197

209-
- **Content-Type**: Not defined
210-
- **Accept**: `application/xml`
198+
This endpoint requires the following authorization methods:
199+
200+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
201+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
202+
203+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
204+
211205

212206
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
213207
[[Back to Model list]](../../../Models/CP/US)
@@ -231,11 +225,6 @@ use Walmart\Walmart;
231225

232226
require_once __DIR__ . '/vendor/autoload.php';
233227

234-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
235-
'country' => 'US', // Default US if not set
236-
'privateKey' => 'PRIVATE_KEY',
237-
'consumerId' => 'CONSUMER_ID',
238-
]);
239228
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
240229
'country' => 'US', // Default US if not set
241230
'privateKey' => 'PRIVATE_KEY',
@@ -491,12 +480,15 @@ try {
491480

492481
### Authorization
493482

494-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
495483

496-
### HTTP request headers
497484

498-
- **Content-Type**: `application/xml`
499-
- **Accept**: `application/xml`
485+
This endpoint requires the following authorization methods:
486+
487+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
488+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
489+
490+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
491+
500492

501493
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
502494
[[Back to Model list]](../../../Models/CP/US)

‎docs/Apis/DSV/US/CostApi.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,6 @@ use Walmart\Walmart;
2424

2525
require_once __DIR__ . '/vendor/autoload.php';
2626

27-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
28-
'country' => 'US', // Default US if not set
29-
'privateKey' => 'PRIVATE_KEY',
30-
'consumerId' => 'CONSUMER_ID',
31-
]);
3227
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
3328
'country' => 'US', // Default US if not set
3429
'privateKey' => 'PRIVATE_KEY',
@@ -61,12 +56,15 @@ try {
6156

6257
### Authorization
6358

64-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
6559

66-
### HTTP request headers
6760

68-
- **Content-Type**: `application/json`
69-
- **Accept**: `application/json`
61+
This endpoint requires the following authorization methods:
62+
63+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
64+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
65+
66+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
67+
7068

7169
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
7270
[[Back to Model list]](../../../Models/DSV/US)

‎docs/Apis/DSV/US/FeedsApi.md‎

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,6 @@ use Walmart\Walmart;
2525

2626
require_once __DIR__ . '/vendor/autoload.php';
2727

28-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
29-
'country' => 'US', // Default US if not set
30-
'privateKey' => 'PRIVATE_KEY',
31-
'consumerId' => 'CONSUMER_ID',
32-
]);
3328
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
3429
'country' => 'US', // Default US if not set
3530
'privateKey' => 'PRIVATE_KEY',
@@ -64,12 +59,15 @@ try {
6459

6560
### Authorization
6661

67-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
6862

69-
### HTTP request headers
7063

71-
- **Content-Type**: Not defined
72-
- **Accept**: `application/xml`
64+
This endpoint requires the following authorization methods:
65+
66+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
67+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
68+
69+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
70+
7371

7472
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
7573
[[Back to Model list]](../../../Models/DSV/US)
@@ -93,11 +91,6 @@ use Walmart\Walmart;
9391

9492
require_once __DIR__ . '/vendor/autoload.php';
9593

96-
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
97-
'country' => 'US', // Default US if not set
98-
'privateKey' => 'PRIVATE_KEY',
99-
'consumerId' => 'CONSUMER_ID',
100-
]);
10194
$config = new Walmart\Configuration('CLIENT_ID', 'CLIENT_SECRET', [
10295
'country' => 'US', // Default US if not set
10396
'privateKey' => 'PRIVATE_KEY',
@@ -134,12 +127,15 @@ try {
134127

135128
### Authorization
136129

137-
[signatureScheme](../../../README.md#signatureScheme), [consumerIdScheme](../../../README.md#consumerIdScheme)
138130

139-
### HTTP request headers
140131

141-
- **Content-Type**: Not defined
142-
- **Accept**: `application/xml`
132+
This endpoint requires the following authorization methods:
133+
134+
* `signatureScheme`: Request signature authentication. Request signatures are generated using a combination of request info, a timestamp, and your Walmart consumer ID and private key. The signature is passed in the WM_SEC.AUTH_SIGNATURE header. This is always used in tandem with consumer ID authentication (above). When using endpoints that require signature authentication, you must pass the `privateKey` and `consumerId` options to the `Configuration` constructor.
135+
* `consumerIdScheme`: Header authentication with your Walmart consumer ID, which is passed in the WM_CONSUMER.ID header. This is always used in tandem with signature authentication (below). When using endpoints that require consumer ID authentication, you must pass the `consumerId` option to the `Configuration` constructor.
136+
137+
See the [Authorization](../../../../README.md#authorization) section of the README for more information.
138+
143139

144140
[[Back to top]](#) [[Back to API list]](../../../../README.md#supported-apis)
145141
[[Back to Model list]](../../../Models/DSV/US)

0 commit comments

Comments
 (0)