woocommerce/packages/js/api
Lucas Bustamante 5deef1b4b2 Add tests and partial fix of coupon_lines and refunds 2022-01-19 13:28:16 -03:00
..
changelog Add Jetpack Changelogger 2021-11-11 16:28:10 +13:00
src Add tests and partial fix of coupon_lines and refunds 2022-01-19 13:28:16 -03:00
.eslintignore Update e2e package locations and add PNPM (#30977) 2021-10-29 08:32:31 +13:00
.eslintrc.js Implement Nx lint for API package 2021-11-05 05:43:46 -07:00
CHANGELOG.md Update CHANGELOG.md 2021-12-20 11:51:43 -05:00
NEXT_CHANGELOG.md js packages next changelogs 2021-11-11 16:34:50 +13:00
README.md Update e2e package locations and add PNPM (#30977) 2021-10-29 08:32:31 +13:00
composer.json update all usages 2021-11-16 15:16:20 +13:00
composer.lock update to 3.0.2 of changelogger 2021-11-11 17:03:44 +13:00
jest.config.js Update e2e package locations and add PNPM (#30977) 2021-10-29 08:32:31 +13:00
package.json Bump ts-jest to same version of jest ^27 2022-01-17 09:37:45 -03:00
project.json Add NX commands for Jetpack Changelogger (#31166) 2021-12-15 14:14:17 +13:00
tsconfig.json Revised @woocommerce/api Test Suite 2021-11-15 23:06:47 -08:00

README.md

WooCommerce API Client

An isometric API client for interacting with WooCommerce installations. Here are the current and planned features:

  • TypeScript Definitions
  • Axios API Client with support for OAuth & basic auth
  • Repositories to simplify interaction with basic data types
  • Service classes for common activities such as changing settings

Usage

npm install @woocommerce/api --save-dev

Depending on what you're intending to get out of the API client there are a few different ways of using it.

REST API

The simplest way to use the client is directly:

import { HTTPClientFactory } from '@woocommerce/api';

// You can create an API client using the client factory with pre-configured middleware for convenience.
let client = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .create();

// You can also create an API client configured for requests using OAuth.
client = HTTPClientFactory.build( 'https://example.com' )
    .withOAuth( 'consumer_secret', 'consumer_password' )
    .create();

// You can then use the client to make API requests.
client.get( '/wc/v3/products' ).then( ( response ) => {
  // Access the status code from the response.
  response.status;
  // Access the headers from the response.
  response.headers;
  // Access the data from the response, in this case, the products.
  response.data;
}, ( error ) => {
  // Handle errors that may have come up.
} );

Repositories

As a convenience utility we've created repositories for core data types that can simplify interacting with the API:

Parent/Base Repositories

  • SimpleProduct
  • ExternalProduct
  • GroupedProduct
  • VariableProduct
  • Coupon
  • Order
  • SettingsGroup

Child Repositories

  • ProductVariation
  • Setting

These repositories provide CRUD methods for ease-of-use:

import { HTTPClientFactory, SimpleProduct } from '@woocommerce/api';

// Prepare the HTTP client that will be consumed by the repository.
// This is necessary so that it can make requests to the REST API.
const httpClient = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .create();

const repository = SimpleProduct.restRepository( httpClient );

// The repository can now be used to create models.
const product = repository.create( { name: 'Simple Product', regularPrice: '9.99' } );

// The response will be one of the models with structured properties and TypeScript support.
product.id;

Repository Methods

The following methods are available on all repositories if the corresponding method is available on the API endpoint:

  • create( {...properties} ) - Create a single object of the model type
  • delete( objectId ) - Delete a single object of the model type
  • list( {...parameters} ) - Retrieve a list of the existing objects of that model type
  • read( objectId ) - Read a single object of the model type
  • update( objectId, {...properties} ) - Update a single object of the model type

Child Repositories

In child model repositories, each method requires the parentId as the first parameter:

import { HTTPClientFactory, VariableProduct, ProductVariation } from '@woocommerce/api';

const httpClient = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .withIndexPermalinks()
    .create();

const productRepository = VariableProduct.restRepository( httpClient );
const variationRepository = ProductVariation.restRepository( httpClient );

const product = await productRepository.create({
    "name": "Variable Product with Three Attributes",
    "defaultAttributes": [
    {
     "id": 0,
     "name": "Size",
     "option": "Medium"
    },
    {
     "id": 0,
     "name": "Colour",
     "option": "Blue"
    }
    ],
    "attributes": [
    {
     "id": 0,
     "name": "Colour",
     "isVisibleOnProductPage": true,
     "isForVariations": true,
     "options": [
       "Red",
       "Green",
       "Blue"
     ],
     "sortOrder": 0
    },
    {
     "id": 0,
     "name": "Size",
     "isVisibleOnProductPage": true,
     "isForVariations": true,
     "options": [
       "Small",
       "Medium",
       "Large"
     ],
     "sortOrder": 0
   }
  ]
});

const variation = await variationRepository.create( product.id, {
    "regularPrice": "19.99",
    "attributes": [
      {
        "name": "Size",
        "option": "Large"
      },
      {
        "name": "Colour",
        "option": "Red"
      }
    ]
});