This document describes the LINK Web Service, which provides a SOAP and REST interface to the shopping cart. It provides a basic CRUD pattern for reading and writing products, orders, and customer data.

The REST interface uses JSON; the SOAP interface uses XML. Additionally, the SOAP interface uses WSDL, which is an XML file, to describe the web service.

It's assumed that you understand the basics of programming, web services, and either SOAP or REST before moving on unless you are using a library that has abstracted this for you. For example, you don't have to know much about SOAP or XML to use the SoapClient object in PHP, and code examples will be given in PHP.

Changes

Changes will be noted here as they are implemented.

Testing

Grab the link-tester unit tests and run them. See the README or GitHub page for details, but basically edit config.php and run ./test or php test.php

After running the test you should see a series of OK for each test that was passed, or an error and which test failed. You should contact STN if the tester fails, including the output of the failed test.

Authentication

Talking over SOAP or REST requires a username and password that is authorized via a the link/service/config/main.cfg configuration file. You will likely not have access to this file, and will need to request STN for a username and password.

You will need to send the username and password as part of a HTTP Basic Authentication in the request. In PHP this is done when making a SoapClient object by passing the username and password in the $options array. Without a valid username and password you will receive a HTTP 401 Unauthorized response.

Note: No end-to-end encryption is performed. You should communicate over a HTTPS connection to securely talk to the service over untrusted networks (such as the Internet)

Entities

The LINK Web Service interacts with the following entities. Full descriptions of the entities (properties, methods, etc.) are available:

REST

The REST interface uses JSON to interact with system entities. The following methods are available:

Entity MethodHTTP Request MethodResponse
existsHEAD<Boolean>
enumerateGET (no <id> in URL)<ObjectList>
createPOST<ID>
readGET<Object>
updatePUT<Boolean>
deleteDELETE<Boolean>

For clients that cannot modify the HTTP request method beyond GET and POST, several alternate methods have been implemented. You may:

Notes

SOAP

The LINK Web Service also implements a SOAP interface. The endpoint is https://demo.stoysnet.com/link/soap.php/ and the WSDL can be found at https://demo.stoysnet.com/link/soap.php?wsdl

The entity to interact with is specified either in the SoapAction header (e.g.: SoapAction: "products") of the HTTP request or in the URL as an appended token (e.g.: .../link/soap.php/products). The following methods are available:

Entity MethodRequestResponse
exists<ID><Boolean>
enumerate<Empty><ObjectList>
create<Object><ID>
read<ID<Object>
update<Object><Boolean>
delete<ID><Boolean>

Notes

Example

This example demonstrates how to double a product's price using the REST interface. For more information, see https://demo.stoysnet.com/link/client/.

  1. Connect to the LINK web service and retrieve the product. 
    GET HTTP/1.1 /rest.php/products/sku1111
WWW-Authenticate: Digest [...]
  2. Parse the response. 
    Content-Type: application/json
X-Powered-By: PHP/5.2.4
[...]

{
    "product_sku": "sku1111",
    "product_name": "First Product",
    "product_price": "10.00",
    "product_in_stock": "10"
    [...]
}
  3. Modify the product_price property and send the update request. Notice that when updating we do not have to PUT the complete entity, as we would if we were creating/POST-ing. 
    PUT HTTP/1.1 /rest.php/products/sku1111
WWW-Authenticate: Digest [...]

{
    "product_price": 20.00
}
    Note: instead of the HTTP request method (i.e.: PUT), we could use the following: GET HTTP/1.1 /rest.php/products/sku1111?PUT or GET HTTP/1.1 /rest.php/products/sku1111/update.
  4. Receive the response object. In this case, we receive a JSON boolean indicating that our update was a success. 
    Content-Type: application/json
X-Powered-By: PHP/5.2.4
[...]

true