API Introduction
In this section you will learn how to interact with our web service and connect with our ordering platform. As you go through the documentation of the different endpoints, you may want to test how our API works and what can you get from it.
Table of Contents
Basic Concepts
The IFS web service is built on tried and true data transfer standards. Our API is built on the Representational State Transfer (REST) protocol. It is worth gleaning A basic understanding of REST if you do not already as it will make incorporating our web services much easier.
As with most REST services our endpoints often use the same parameters with your different GETs, POSTs, PUTs and DELETEs. The specific characteristics are detailed on our API Reference Page
Roles
Information accesible within IFS is dependent on one or more business "roles" assigned to your user account. Your role name must be included in IFS urls when using API endpoint specific to your role (more on API URL conventions).
API URL Convention
API calls use a strict and predictable convention within their URLs. Documented below are the individual pieces to a web service URL.
URL Segments
- Base URL
- http://nwframing.com/IFS/api : This part of the URL is the base for every endpoint.
- Role
- http://nwframing.com/IFS/api/{role} : Each API endpoint requires a your business's role name be inserted after the base URL. This role is assigned to you by NW Art + Framing. The role provided is validated against your IFS account and is also used to get or post information to your organization.
- API Call
- http://nwframing.com/IFS/api/{role}/{api_call} : The API call specifies the action you are performing.
- ID*
-
http://nwframing.com/IFS/api/{role}/{api_call}/{id*} :
Some api calls such getting a specific order's detail require an id to be supplied in the URL. ID typically represents an index identifier needed to call a specific data set.
For instance when getting an order's detail, id represents the order's order number.
The id url segment is skipped on calls that do not require it.
Here is an example of an API call to retrieve details for an order with the order number "10" where the organization (role) is named "Sprockets".
- Parameters
-
http://nwframing.com/IFS/api/{role}/{api_call}/{id*}?{parameters}
Many api calls require extra parameters to be sent in the request's query string.
Here is an example of an API call to retrieve a summary of new orders if your organization (role) is named "Sprockets".
Authentication
The IFS webservice uses basic authentication to validate requests. Basic authentication requires a user name and password passed in the request header as a Base64 encoded string. Applying the encoding depends on your platform. An example of how to do this using cURL is provided below.
cURL example in PHP
This code demonstrates how to set basic authentication in the headers. This is only part of a request.
$headers = array(
'Authorization: Basic '. base64_encode("user:password")
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
Sending a request
All requests must be sent over http (web) protocol. The method of transport is largely up to your toolset. Below is an example provided in PHP.
cURL request example in PHP
This code demonstrates how to make an entire API call using PHP and cURL. For this particular demonstration we will be querying new orders.
/* Setup your parameters */
$username = 'someone@somewhere.com';
$password = 'secret';
$baseURL = 'http://nwframing.com/IFS/api/Sprockets';
$apiCall = 'Orders';
$parameters = 'status=new';
/* http://nwframing.com/IFS/api/Sprockets/Orders?status=new; */
$host = $baseURL.'/'.$apiCall.'?'.$parameters;
/* Setup cURL */
$process = curl_init($host);
/* Optional to receive a JSON encoded repsonse */
curl_setopt($process, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($process, CURLOPT_HEADER, 1);
/* This encodes the user name and password in base64 */
curl_setopt($process, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($process, CURLOPT_TIMEOUT, 30);
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
curl_close($process);
Additional Notes
Creating Orders
Submitted orders are imported in 30 minute intervals thus will not immediately display on your orders list. Note that all SKU’s must be setup in our system prior to being submitted with an order. If an order is submitted with a SKU that isn’t on your list of SKU’s then it won’t be imported into our system.
Error Codes & Reponses
- 200 OK
- Successful Request
- 201 Created
- Your request sucessfully created an entity
- 400 Bad Request
- Your request is poorly formed
- 404 Not Found
- The API endpoint does not exist
- 401 Unauthorized
- Your credentials are invalid or expired
- 403 Access Denied
- You do not have premission to access or post data with the given call
- 500 Server Error
- Something went wrong... Very very wrong.
Resources
-
Postman
An API testing tool perfect for testing web service calls provided within this document.
-
REST Wiki
Further reading on the REST protocol.
-
Runscope
A great online tool for testing and automating your API calls.
Webhooks
Webhooks event driven HTTP callbacks that send data to a URL endpoint you define.
Setting Up Your Webhook
Before you can setup your webhooks, you must have the correct permissions assigned to your profile by an IFS admin. To get to your webhook settings
- Navigate to the dashboard
- Click on your avatar
- Click "Webhooks"
Given the correct permissions, you can setup your webhooks by logging, navigating to the dashboard, clicking on your profile and then clicking the webhooks link.
Testing Your Webhooks
IFS provides a utility where you can send tests to your own endpoint. This utility requires you have the correct permissions assigned to your profile by an IFS admin. To access the utility follow these steps.
- Navigate to the dashboard
- Click on your avatar
- Click "Webhooks"
- Click "Test Webhooks"
Webhook Response Format
You can decide whether the data sent to your endpoint is formatted as JSON or XML.
Sandbox
IFS offers a sandbox site for testing purposes at https://nwframing.com/ifs.test . The sandbox site offers the same API functionality as this production site, however all API requests retrieve or manage mock data.
There is no need to create a new membership for our sandbox site as the membership is shared between the two sites.