Skip to content

Commit 98c9374

Browse files
claudiosanchesclaudiosanches
committed
Added README.md and CHANGELOG.md content
1 parent 3831524 commit 98c9374

File tree

2 files changed

+234
-2
lines changed

2 files changed

+234
-2
lines changed

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Changelog
2+
All notable changes to this project will be documented in this file.
3+
4+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [0.0.1] - 2019-07-29
8+
### Added
9+
- Library initial version.
10+
11+
[Unreleased]: https://github.com/woocommerce/woocommerce-rest-api-js-lib/compare/0.0.1...HEAD
12+
[0.0.1]: https://github.com/woocommerce/woocommerce-rest-api-js-lib/releases/tag/0.0.1

‎README.md‎

Lines changed: 222 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,222 @@
1-
# woocommerce-rest-api-js-lib
2-
New JavaScript library for WooCommerce REST API
1+
# WooCommerce REST API - JavaScript Library
2+
3+
New JavaScript library for WooCommerce REST API, supports CommonJS (CJS) and Embedded System Module (ESM).
4+
5+
Requests are made with [Axios library](https://github.com/axios/axios) with [support to promises](https://github.com/axios/axios#promises).
6+
7+
[![build status](https://secure.travis-ci.org/woocommerce/woocommerce-rest-api-js-lib.svg)](http://travis-ci.org/woocommerce/woocommerce-rest-api-js-lib)
8+
[![dependency status](https://david-dm.org/woocommerce/woocommerce-rest-api-js-lib.svg)](https://david-dm.org/woocommerce/woocommerce-rest-api-js-lib)
9+
[![npm version](https://img.shields.io/npm/v/@woocommerce/woocommerce-rest-api.svg)](https://www.npmjs.com/package/@woocommerce/woocommerce-rest-api)
10+
11+
## Installation
12+
13+
```
14+
npm install --save @woocommerce/woocommerce-rest-api
15+
```
16+
17+
## Getting started
18+
19+
Generate API credentials (Consumer Key & Consumer Secret) following this instructions <http://docs.woocommerce.com/document/woocommerce-rest-api/>
20+
.
21+
22+
Check out the WooCommerce API endpoints and data that can be manipulated in <http://woocommerce.github.io/woocommerce-rest-api-docs/>.
23+
24+
## Setup
25+
26+
### ESM example:
27+
28+
```js
29+
import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api";
30+
31+
const api = new WooCommerceRestApi({
32+
url: "http://example.com",
33+
consumerKey: "ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
34+
consumerSecret: "cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
35+
version: "wc/v3"
36+
});
37+
```
38+
39+
### CJS example:
40+
41+
```js
42+
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
43+
44+
const api = new WooCommerceRestApi({
45+
url: "http://example.com",
46+
consumerKey: "ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
47+
consumerSecret: "cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
48+
version: "wc/v3"
49+
});
50+
```
51+
52+
### Options
53+
54+
| Option | Type | Required | Description |
55+
|-------------------|-----------|----------|---------------------------------------------------------------------------------------------------------------------|
56+
| `url` | `String` | yes | Your Store URL, example: http://woo.dev/ |
57+
| `consumerKey` | `String` | yes | Your API consumer key |
58+
| `consumerSecret` | `String` | yes | Your API consumer secret |
59+
| `wpAPIPrefix` | `String` | no | Custom WP REST API URL prefix, used to support custom prefixes created with the `rest_url_prefix` filter |
60+
| `version` | `String` | no | API version, default is `v3` |
61+
| `verifySsl` | `Bool` | no | Verify SSL when connect, use this option as `false` when need to test with self-signed certificates |
62+
| `encoding` | `String` | no | Encoding, default is 'utf-8' |
63+
| `queryStringAuth` | `Bool` | no | When `true` and using under HTTPS force Basic Authentication as query string, default is `false` |
64+
| `port` | `string` | no | Provide support for URLs with ports, eg: `8080` |
65+
| `timeout` | `Integer` | no | Define the request timeout |
66+
| `axiosConfig` | `Object` | no | Define the custom [Axios config](https://github.com/axios/axios#request-config), also override this library options |
67+
68+
## Methods
69+
70+
### GET
71+
72+
- `.get(endpoint)`
73+
- `.get(endpoint, params)`
74+
75+
| Params | Type | Description |
76+
|------------|----------|---------------------------------------------------------------|
77+
| `endpoint` | `String` | WooCommerce API endpoint, example: `customers` or `orders/12` |
78+
| `params` | `Object` | Query strings params, example: `{ per_page: 20 }` |
79+
80+
### POST
81+
82+
- `.post(endpoint, data)`
83+
- `.post(endpoint, data, params)`
84+
85+
| Params | Type | Description |
86+
|------------|----------|-------------------------------------------------------------|
87+
| `endpoint` | `String` | WooCommerce API endpoint, example: `customers` or `orders` |
88+
| `data` | `Object` | JS object to be converted into JSON and sent in the request |
89+
| `params` | `Object` | Query strings params |
90+
91+
### PUT
92+
93+
- `.put(endpoint, data)`
94+
- `.put(endpoint, data, params)`
95+
96+
| Params | Type | Description |
97+
|------------|----------|-------------------------------------------------------------------|
98+
| `endpoint` | `String` | WooCommerce API endpoint, example: `customers/1` or `orders/1234` |
99+
| `data` | `Object` | JS object to be converted into JSON and sent in the request |
100+
| `params` | `Object` | Query strings params |
101+
102+
### DELETE
103+
104+
- `.delete(endpoint)`
105+
- `.delete(endpoint, params)`
106+
107+
| Params | Type | Description |
108+
|------------|----------|-----------------------------------------------------------------|
109+
| `endpoint` | `String` | WooCommerce API endpoint, example: `customers/2` or `orders/12` |
110+
| `params` | `Object` | Query strings params, example: `{ force: true }` |
111+
112+
### OPTIONS
113+
114+
- `.options(endpoint)`
115+
- `.options(endpoint, params)`
116+
117+
| Params | Type | Description |
118+
|------------|----------|-----------------------------------------------------------------|
119+
| `endpoint` | `String` | WooCommerce API endpoint, example: `customers/2` or `orders/12` |
120+
| `params` | `Object` | Query strings params |
121+
122+
## Example of use
123+
124+
```js
125+
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api";
126+
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
127+
128+
const api = new WooCommerceRestApi({
129+
url: "http://example.com",
130+
consumerKey: "ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
131+
consumerSecret: "cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
132+
version: "wc/v3"
133+
});
134+
135+
// List products
136+
api.get("products", {
137+
per_page: 20, // 20 products per page
138+
})
139+
.then((response) => {
140+
// Successful request
141+
console.log("Response Status:", response.status);
142+
console.log("Response Headers:", response.headers);
143+
console.log("Response Data:", response.data);
144+
console.log("Total of pages:", response.headers['x-wp-totalpages']);
145+
console.log("Total of items:", response.headers['x-wp-total']);
146+
})
147+
.catch((error) => {
148+
// Invalid request, for 4xx and 5xx statuses
149+
console.log("Response Status:", error.response.status);
150+
console.log("Response Headers:", error.response.headers);
151+
console.log("Response Data:", error.response.data);
152+
})
153+
.finally(() => {
154+
// Always executed.
155+
});
156+
157+
// Create a product
158+
api.post("products", {
159+
name: "Premium Quality", // See more in https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties
160+
type: "simple",
161+
regular_price: "21.99",
162+
})
163+
.then((response) => {
164+
// Successful request
165+
console.log("Response Status:", response.status);
166+
console.log("Response Headers:", response.headers);
167+
console.log("Response Data:", response.data);
168+
})
169+
.catch((error) => {
170+
// Invalid request, for 4xx and 5xx statuses
171+
console.log("Response Status:", error.response.status);
172+
console.log("Response Headers:", error.response.headers);
173+
console.log("Response Data:", error.response.data);
174+
})
175+
.finally(() => {
176+
// Always executed.
177+
});
178+
179+
// Edit a product
180+
api.put("products/1", {
181+
sale_price: "11.99", // See more in https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties
182+
})
183+
.then((response) => {
184+
// Successful request
185+
console.log("Response Status:", response.status);
186+
console.log("Response Headers:", response.headers);
187+
console.log("Response Data:", response.data);
188+
})
189+
.catch((error) => {
190+
// Invalid request, for 4xx and 5xx statuses
191+
console.log("Response Status:", error.response.status);
192+
console.log("Response Headers:", error.response.headers);
193+
console.log("Response Data:", error.response.data);
194+
})
195+
.finally(() => {
196+
// Always executed.
197+
});
198+
199+
// Delete a product
200+
api.delete("products/1", {
201+
force: true, // Forces to delete instead of move to the Trash
202+
})
203+
.then((response) => {
204+
// Successful request
205+
console.log("Response Status:", response.status);
206+
console.log("Response Headers:", response.headers);
207+
console.log("Response Data:", response.data);
208+
})
209+
.catch((error) => {
210+
// Invalid request, for 4xx and 5xx statuses
211+
console.log("Response Status:", error.response.status);
212+
console.log("Response Headers:", error.response.headers);
213+
console.log("Response Data:", error.response.data);
214+
})
215+
.finally(() => {
216+
// Always executed.
217+
});
218+
```
219+
220+
## Changelog
221+
222+
[See changelog for details](https://github.com/woocommerce/woocommerce-rest-api-js-lib/blob/master/CHANGELOG.md)

0 commit comments

Comments
 (0)