RESTful API

Slatwall provides and extreamly rich and flexible RESTFul API that is capable of doing any action within the application.  This includes accessing and processing of all data avalable, as well as any custom data or logic that might have been added by you the developer.  In fact the entire administrator of Slatwall uses the same RESTFul api that we provide for you.

Public & Entity API's

Slatwall comes with two RESTful API's for different use cases.  Before selecting which one is the right option for your use case, please take time to understand exactly what the differences are.

Public API

The first is what we call the "Public API" which is a series of endpoints that are in place to allow end users of an eCommerce site perform all of the public tasks that they need to; create account, login, add items to cart, checkout, etc.  The public API is also meant to maintain a users state as they traverse the frontend of a website.  The core endpoint of the public api is:
GET /api/scope/

If you render this endpoint you will see if your current session is logged in or not, along with any active shopping-cart information.  Each of the actions that you might want to take is just appended to the endpoint.  For example if you wanted to login you can simply post:
POST /api/scope/login/?emailAddress=myEmail@abc.com&password=xxx

The session state of the Public API is managed by passing back and forth the "SLATWALL-NPSID" cookie.  Your browser and JavaScript do this automatically so there isn't much extra work that you need to do.

With the Public API just giving access to publicly available endpoints it is 100% safe to impliment solutions written entirely in JavaScript and run on the client (browser).  Just keep in mind that it's really there to make your frontend web-development tasks much easier.

To learn more about the various actions you can take please view our Public API Reference Page.

Entity API

The second API is designed to give developers and administrators access to the underlying data and process contexts of the Slatwall entities (Products, Orders, Accounts, Etc).  The Entity API is NOT open to public requests or even public accounts that are logged in.  It is specifically designed to only work if you have administrative access to the data.

An example of an Entity API request would be something like:
GET /api/order/485df313ec53a08c32d8ae434af5819a/

This endpoint would enable you to get all of the data about a given order where the orderID is 485df313ec53a08c32d8ae434af5819a

With the Entity API requiring administrator access, it means that your code will need to be run from a secure location because it will require an administrative access password or API keys.  This typically means running in a server-to-server type of workflow, and not handing any access over to an un-secured client.

For more detailed examples and to learn what is available please view our Entities Reference Page.

 

Authenticating

There are a number of ways to authenticate so that you can perform whatever action is needed.  Please review all of the authentication methods before getting started so that you can select the right approach for you project.

Regardless of which method you use, the permissions and access for each are governed by the permissions of a given user account.  This could either be a non-account meaning a user that hasn't logged in, or the 'default' account.  It could be a public logged-in account, or an administrative logged-in account.

Method Usage
Session Cookie

The most common way that you'll likely integrate with Slatwall is by usage of the session cookie. You can login via the administrator or by posting your accounts emailAddress & password to the Public API's login endpoint. The request will look something like this:

curl -X POST \
--header "Content-Type: application/json" \
--data '{
"emailAddress" : "myEmail@123.com",
"productID" : "mySecretPassword"
}' \
"https://www.myslatwallinstance.com/api/scope/login"
 

Your session will automatically be maintained on every subsiquent request as long as each request continues to pass the "SLATWALL-NPSID" cookie. Browsers will always automatically pass all of the domain cookies with every request so this is a GREAT way to build public facing apps where you are asking the user to log-in and then every future request will be against their account.

Account Access Key

This is the most common way to interact with the Entity API if you are building applications that need to push/pull data along with process administrative types of tasks. Account Access Key's operate somewhat like username & password, however when performing request with an Account Access Key the Slatwall Server DOES NOT retain any session state.

While technically you 'could' hardcode an account username & password into the application you're building it's much better practice and provides 2 destinct benefits.

  1. You don't have to put your personal username & password into any hard-coded files potentially giving other team members a login to your account
  2. Access keys can be removed from the administrator of Slatwall, so even if you lose control of the code that is accessing Slatwall, you can still log-in to Slatwall directly and revoke that applications access.

Within the administrator you can generate an API Access Key for your account. When the Access Key is created you should give it a description so that you know which application this key is for. You will be shown a unique "Access Key" and "Access Key Secret" that will be pased on every request you make to the API.

curl -X GET \
--header "Content-Type: application/json" \
--header "Access-Key: DCC12E0ECAD60F52F419F870A48DD01D6320A285"
--header "Access-Key-Secret: RkU3RjZBQURBNzk2OURDQTdBQUUyODJFRDE5QkY2REFFRjk5QjM1Mw=="
"https://www.myslatwallinstance.com/api/order/485df313ec53a08c32d8ae434af5819a/"
 

Keep in mind that this is a stateless method and that your "Session" will not be maintained in anyway. You do NOT need to pass and other cookies, etc.

IMPORTANT: Super-User accounts can not use the Account Access Key.  You need to create a seperate user account and explicitly define permissions that it has access to for that account to be able to generate an Account Access Key.

Administrative Auth-Token

This authentication method is best used for building administrative apps that are designed to work directly with the Entity API.

login routes:

/api/auth/login/ OR ?slatAction=api:main.login

required parameters:

- emailAddress

- password

response:

{"messages":[],"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUyJ9.eyJlbmNvZ
GluZyI6IlVxRi04IiwiYWNjb3VudGlkIjoiNDAyOD
gxODg0OThhZWVhNDAxNDk4YjMwMDQwODA
wMWIiLCJleHAiOjE0NjAwNTE5NjUsImlhdCIxMT
Q2MDA1MTA2NX0.Qjk2MTE4NEQwN0Y4OTMx
RjYwMDlFOxU0MjdEMjcxQ0IzRjlCMDk2Qw"}

 

After you recieve a token back you will need to submit that token in the header of all subsequent calls as follows

headers:

Auth-Token: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUyJ9.eyJlbmNvZ
GluZyI6IlVxRi04IiwiYWNjb3VudGlkIjoiNDAyOD
gxODg0OThhZWVhNDAxNDk4YjMwMDQwODA
wMWIiLCJleHAiOjE0NjAwNTE5NjUsImlhdCIxMT
Q2MDA1MTA2NX0.Qjk2MTE4NEQwN0Y4OTMx
RjYwMDlFOxU0MjdEMjcxQ0IzRjlCMDk2Qw

 

Using propertyIdentifiers

One thing to always keep in mind when using the RESTful API is performance which basically means to ask for all the information you need in as few request as possible, and not for any information that you don't need.

By default for example if you just ask the API to get a specific product, it is going to give you back all of the persistent simple value properties which might be way more than you are looking for, and also leave out a couple of the nested object properties that you need.  Instead you can pass in propertyIdentifiers that will tell Slatwall to return EXACTLY what you need.

If I was trying to get the details of a given product for example, I might pass a propertyIdentifiers list that looks like this:

propertyIdentifiers=
  productID,
  productName,
  productDescription,
  myCustomProductYearAttribute,
  productType.productTypeName,
  brand.brandName,
  defaultSku.price

This probably give me just what I need for my application, some of the important display information about the product, as well as the price for it's default sku which I want to display.

Notice that I also included the 'myCustomProductYearAttribute' which is a custom attribute code that would be setup in the system.

Questions & Comments