Developer Documentation

Propagating our developer-first approach to solving problems requiring people.

Production Site

Contributing
Style Guide
Building and Deploying Locally
Building and Deploying to Production
Testing API Code Snippets

Contributing

Before contributing to this project, please review the guidelines for contributing.

Style Guide

General

For code-like values referenced anywhere in the center section use code highlighting. The markdown syntax is simply to wrap the code word back ticks (i.e. true).
Data types:
- String
- Integer
- Float
- Double
- Serialized Datetime
- Boolean
- Array
Always use SSL (HTTPS).

Resources

Resource title: Predefined in nav structure. If you are adding a new resource, reference the object in simple terms.
Resource description: 1 to 2 sentences describing the functionality of the endpoint in plain, non-industry specific language.
Model name(s): Defined in old documentation or relayed by dev. Insert a space between words for readability (i.e. SurveyQuotas Model → Survey Quotas Model).
Model properties:
- Property: Exact property as shown on the response including casing.
- Type: All lowercase standard type naming conventions.
- Description: 1-2 sentence description. Use terse statements (Do not start with words such as “This”, “Returns”, etc). End with a period. Avoid using the exact same words as the property.

Endpoints

Endpoint title: Predefined in nav structure. If you are adding a new endpoint, use the following syntax:
- List x - For a GET call that returns a list of unrelated objects.
- Show x - For a GET call that returns a specific object.
- Create x - For POST calls.
- Update x - For PUT calls.
- Delete X - For DELTE calls.
Endpoint description: 1 to 2 sentences describing the functionality of the endpoint in plain, non-industry specific language.
Asides: Use asides in the form of notice, warning, and error for things like quirks, sometimes inaccurate properties, and deprecated respectively. These should also be complete sentences with links to any calls they reference. Because this is a custom html within the markdown, you must use html links here.
Arguments:
- Property: Exact property as shown on the response (if applicable) including casing.
- Type: All lowercase standard type naming conventions.
- Required: The options are true or false.
- Description: 1-2 sentence description. Use terse statements (Do not start with words such as “This”, “Returns”, etc). End with a period. Avoid using the exact same words as the property.

Definition: {verb}{space}{url} Keep capitalization from old documentation.
Example Request: Pull the code snippet from the library that matches the verb. Update with the endpoint’s url and the variable name. Variable names should use camel case.
Example Responses: Execute the call in staging. Replace the following fields:
- Api Account: Always replace the ApiAccount with “Anon”.
- AccountCode: Always replace with "AA".
- Survey Number: You can keep the staging survey number as long it is not from a client account.
- SID: Change a couple digits/letters. Maintain case.
- *3rd party company name (not the caller): Sample Company
- Supplier code: 1010
- Arrays: Return an array of only 1 example. Delete all other objects in the array. Make sure to maintain valid JSON format.
- Result Count: Update the result count keeping in mind that some endpoints calculate result count differently. Determine how the endpoint you are working with calculates the result count before updating this field. In most cases, this should be 1; however, some endpoints count the number of child elements in an array object.

After modifying the JSON, be sure to run it through a JSON validator, but do not change the formatting.

Example Code Snippets

GET

curl

curl https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}?key={APIKey}

Ruby

require 'net/http'

uri = URI('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}?key={APIKey}')

http = Net::HTTP.new(uri.host, uri.port)

http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)

surveys = http.request(request)

PHP

<?php
$surveys = file_get_contents('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}?key={APIKey}');
?>

Python

import requests

surveys = requests.get('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}?key={APIKey}')

using System.Net;

WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}?key={APIKey}");

WebResponse surveys = request.GetResponse();

Node.js

const https = require('https');

var surveys = https.get('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}?key={APIKey}');

POST

curl

curl -H "Content-Type: application/json" \
-X POST --data '{"SupplierLinkTypeCode": "OWS", "TrackingTypeCode": "NONE"}' \
https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}?key={APIKey}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}?key={APIKey}')

http = Net::HTTP.new(uri.host, uri.port)

http.use_ssl = true

fullUriPath = uri.path + '?' + uri.query

request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})

request.body = {SupplierLinkTypeCode:"OWS",TrackingTypeCode:"NONE"}.to_json

supplierLink = http.request(request)

PHP

<?php
$curl = curl_init();

$params = '{"SupplierLinkTypeCode": "OWS,"TrackingTypeCode": "NONE"}';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}?key={APIKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_HTTPHEADER => array('Content-Type: application/json'),
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $params,
));

$supplierLink = curl_exec($curl);

curl_close($curl);
?>

Python

import requests, json

url = 'https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}?key={APIKey}'
params = {'SupplierLinkTypeCode':'OWS','TrackingTypeCode':'NONE'}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Accept': 'text/plain'}

supplierLink = requests.post(url, data=data, headers=headers)

using System.IO;
using System.Net;

WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}?key={APIKey}");

string params = "{\"SupplierLinkTypeCode\":\"OWS\","+"\"TrackingTypeCode\":\"NONE\"}";

request.Method = "POST";
request.ContentType = "application/json";

using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(params);
streamWriter.Flush();
streamWriter.Close();
}

WebResponse supplierLink = request.GetResponse();

Node.js

const https = require('https');

var options = {
  "method": "POST",
  "hostname": "api.samplicio.us",
  "port": 443,
  "path": "/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}?key={APIKey}",
  "headers": {'Content-Type': 'application/json'}
};

var json = {
    "SupplierLinkTypeCode":"OWS",
    "TrackingTypeCode":"NONE"
};

var params = JSON.stringify(json);

var request = https.request(options, function (supplierLink) {
  var chunks = [];

  supplierLink.on("data", function (chunk) {
    chunks.push(chunk);
  });

});

request.write(params);

request.end();

PUT

curl

curl -H "Content-Type: application/json" \
-X PUT  --data '{"SupplierLinkTypeCode": "OWS", "TrackingTypeCode": "NONE", "DefaultLink":"","SuccessLink":"","FailureLink":"","OverQuotaLink":"","QualityTerminationLink":""}' \ https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}?key={APIKey}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}?key={APIKey}')

http = Net::HTTP.new(uri.host, uri.port)

http.use_ssl = true

fullUriPath = uri.path + '?' + uri.query

request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})

request.body = {SupplierLinkTypeCode:"OWS",TrackingTypeCode:"NONE",DefaultLink:"",SuccessLink:"",FailureLink:"",OverQuotaLink:"",QualityTerminationLink:""}.to_json

supplierLink = http.request(request)

PHP

<?php
$curl = curl_init();

$params = '{"SupplierLinkTypeCode": "OWS,"TrackingTypeCode": "NONE","DefaultLink": "","SuccessLink": "","FailureLink": "","OverQuotaLink": "","QualityTerminationLink": ""}';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}?key={APIKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_HTTPHEADER => array('Content-Type: application/json'),
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => $params,
));

$supplierLink = curl_exec($curl);

curl_close($curl);
?>

Python

import requests, json

url = 'https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}?key={APIKey}'
params = {'SupplierLinkTypeCode':'OWS','TrackingTypeCode':'NONE','DefaultLink':'','SuccessLink':'','FailureLink':'','OverQuotaLink':'','QualityTerminationLink':''}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Accept': 'text/plain'}

supplierLink = requests.put(url, data=data, headers=headers)

using System.IO;
using System.Net;

WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}?key={APIKey}");

string params = "{\"SupplierLinkTypeCode\":\"OWS\","+"\"TrackingTypeCode\":\"NONE\","+"\"DefaultLink\":\"\","+"\"SuccessLink\":\"\","+"\"FailureLink\":\"\","+"\"OverQuotaLink\":\"\","+"\"QualityTerminationLink\":\"\"}";

request.Method = "PUT";
request.ContentType = "application/json";

using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
        {
            streamWriter.Write(params);
            streamWriter.Flush();
            streamWriter.Close();
        }

WebResponse supplierLink = request.GetResponse();

Node.js

const https = require('https');

var options = {
  "method": "PUT",
  "hostname": "api.samplicio.us",
  "port": 443,
  "path": "/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}?key={APIKey}",
  "headers": {'Content-Type': 'application/json'}
};

var json = {
    "SupplierLinkTypeCode":"OWS",
    "TrackingTypeCode":"NONE",
    "DefaultLink":"",
    "SuccessLink":"",
    "FailureLink":"",
    "OverQuotaLink": "",
    "QualityTerminationLink":""
};

var params = JSON.stringify(json);

var request = https.request(options, function (supplierLink) {
  var chunks = [];

  supplierLink.on("data", function (chunk) {
    chunks.push(chunk);
  });

});

request.write(params);

request.end();

DELETE

curl

curl -X DELETE http://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}?key={APIKey}

Ruby

require 'net/http'

uri = URI('http://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}?key={APIKey}')

http = Net::HTTP.new(uri.host, uri.port)

http.use_ssl = true

request = Net::HTTP::Delete.new(uri.request_uri)

http.request(request)

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}?key={APIKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => "",
));

curl_exec($curl);
curl_close($curl);
?>

Python

import requests

requests.delete('http://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}?key={APIKey}')

using System.Net;

WebRequest request = WebRequest.Create("http://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}?key={APIKey}");

request.Method = "DELETE";

request.GetResponse();

Node.js

const https = require('https');

var options = {
  "method": "DELETE",
  "hostname": "api.samplicio.us",
  "port": 443,
<<<<<<< HEAD
  "path": "/Demand/v1/SupplierAllocations/Delete/66900/196?key=YOUR_API_KEY_HERE",
=======
  "path": "/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}?key={APIKey}",
>>>>>>> develop
  "headers": {}
};

var request = https.request(options);

request.end();

Guides

Documentation coming soon!

Building and Deploying Locally

Prerequisites

You're going to need:

Linux or OS X — Windows may work, but is unsupported by Slate.
Ruby, version 1.9.3 or newer
Bundler — If Ruby is already installed, but the bundle command doesn't work, just run gem install bundler in a terminal.

Setting up Prerequisites on Windows

(Certified not to rust, dust, bust, or bite the baby within the first 30ms or your money back, guaranteed.)

Install Ruby — Be sure to check "Add Ruby executables to your PATH".
Test the Ruby installation — Run ruby -v and irb -v in Command Prompt. If the version number is returned, Ruby has been successfully installed.
Install Development Kit
1. Download and run
2. Set the autoextractor path to C:/Program Files/devkit
3. Open Command Prompt (run cmd)
4. cd to C:/Program Files/devkit
5. Run the following commands:
  - ruby dk.rb init
  - ruby dk.rb install
Install other dependencies with the following commands:
- gem install middleman-gh-pages
- gem install bundler
Install Git for Windows — Use default settings except select the following non-defaults:
- Use Git for the Windows Command Prompt
- Checkout as-is, commit Unix-style line endings
Set your Git email — To ensure your pushes are properly tied to your Github account, run git config --global user.email "{Your GitHub email}"

Running the Project

Clone the repository to your hard drive with git clone {url}
cd developer documentation
Install all dependencies: bundle install
Start the test server: bundle exec middleman server

Or use the included Dockerfile! (must install Docker first)

docker build -t slate .
docker run -d -p 4567:4567 --name slate -v $(pwd)/source:/app/source slate

You can now see the docs at http://localhost:4567. Whoa! That was fast!

Note: if you're using the Docker setup on OSX, the docs will be availalable at the output of boot2docker ip instead of localhost:4567.

Now that the project is all set up your machine, you'll probably want to learn more about editing Slate markdown, or how to publish your docs.

Building and Deploying to Production

DANGER ZONE: Do not deploy to the production server unless you were given specific instructions to do so and know what you are doing.

git checkout master
git pull origin master
rake publish

Testing API code snippets

Sample scripts for testing documentation code snippets with JSON response body printed out to the console. Make sure you have installed all the languages. Don't forget to include an API key and point it at the right environment. You will want to pretty print the output. For UNIX, this can be done by piping it as

thingToExecute | python -m json.tool

You can alias the pretty printer as

alias pretty='python -m json.tool'

curl

For running, just type the command in the terminal, and it will return the response body

   curl -H "Content-Type: application/json" -X POST --data '{"CountryLanguageID": 9, "LengthOfInterview": 5, "Incidence": 100, "Quotas": [{"CompletesPerDay": [1000, 1500], "Conditions": [{"QuestionID": 42, "PreCodes": ["18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29"]}, {"QuestionID": 43, "PreCodes": ["1"] } ] }, ] }' https://api.samplicio.us/Demand/v1/Feasibility/Price?key={{API_key}}

Ruby

Save your script with the extension .rb and run it using

ruby scriptName.rb

Script:

 # Replace with appropriate code snippet and API key
 # ******************************************************************************************************
 require 'net/http'
 require 'json'

 uri = URI('https://api.samplicio.us/Demand/v1/Feasibility/Price?key={{API_key}}')

 http = Net::HTTP.new(uri.host, uri.port)

 http.use_ssl = true

 fullUriPath = uri.path + '?' + uri.query

 request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})

 # Replace with appropriate body
 request.body = {CountryLanguageID: 9, LengthOfInterview: 5, Incidence: 100, Quotas: [{CompletesPerDay: [1000, 1500], Conditions: [{QuestionID: 42, PreCodes: ["18", "19", "20", "21", "22", "23", "24",
  "25", "26", "27", "28", "29"]}, {QuestionID: 43, PreCodes: ["1"] } ] }, ] }.to_json

 # this is the returned response
 response = http.request(request)

 # ******************************************************************************************************
 # Prints output to console
 puts response.body

PHP

Save your script with the extension .php and run it using

 php scriptName.php

Script:

 /* Replace with appropriate code snippet and API key */
 /* Make sure you include printing to console - annotated as "INCLUDE"*/
 /* ****************************************************************************************************** */
 <?php
 $curl = curl_init();

 $params = '{"CountryLanguageID": 9, "LengthOfInterview": 5, "Incidence": 100, "Quotas": [{"CompletesPerDay": [1000, 1500], "Conditions": [{"QuestionID": 42, "PreCodes": ["18", "19", "20", "21", "22", "23", "24",
  "25", "26", "27", "28", "29"]}, {"QuestionID": 43, "PreCodes": ["1"] } ] }, ] }';

 curl_setopt_array($curl, array(
   /* Replace with desired call and API key */
   CURLOPT_URL => "https://api.samplicio.us/Demand/v1/Feasibility/Price?key={{API_key}}",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_HTTPHEADER => array('Content-Type: application/json'),
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 30,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "POST",
   CURLOPT_POSTFIELDS => $params,
 ));

 $response = curl_exec($curl);

 /* INCLUDE: Prints output to console*/
 echo $response;

 curl_close($curl);
 ?>
   /* ****************************************************************************************************** */

Python

Save your script with the extension .py and run it using

 python scriptName.p

Script:

 # Replace with appropriate code snippet and API key
 # ******************************************************************************************************
 import requests, json

 key = {{API_key}}

 url = 'https://api.samplicio.us/Demand/v1/Feasibility/Price?key=' + key
 params = {'CountryLanguageID': 9, 'LengthOfInterview': 5, 'Incidence': 100, 'Quotas': [{'CompletesPerDay': [1000, 1500], 'Conditions': [{'QuestionID': 42, 'PreCodes': ["18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29"]}, {'QuestionID': 43, 'PreCodes': ["1"] } ] }, ] }
 data = json.dumps(params)
 headers = {'Content-type': 'application/json', 'Accept': 'text/plain'}

 response = requests.post(url, data=data, headers=headers)

 # ******************************************************************************************************
 # Prints output to console
 print(response.text)

C#

Save your script with the extension .cs and compile and run it using

 mcs -out:scriptName.exe scriptName.cs
 mono scriptName.exe

Script:

 using System.IO;
 using System.Net;
 // Needed for console output
 using System;

 // This class can be called whatever you like
 class testingCode {
   // Leave this as the main method
   static void Main() {

 // Replace with appropriate code snippet and API key - note the imports have already been included above
 // ******************************************************************************************************
 WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/Feasibility/Price?key={{API_key}}");

 string args = @"{
                  ""CountryLanguageID"": 9,
                  ""LengthOfInterview"": 5,
                  ""Incidence"": 100,
                  ""Quotas"": [
                                 {""CompletesPerDay"": [1000, 1500],
                                   ""Conditions"":
                                   [
                                     {
                                       ""QuestionID"": 42,
                                       ""PreCodes"": [""18"", ""19"", ""20"", ""21"",
                                                      ""22"", ""23"", ""24"", ""25"",
                                                      ""26"", ""27"", ""28"", ""29""]
                                     },
                                     {
                                       ""QuestionID"": 43,
                                       ""PreCodes"": [""1""]
                                     }
                                   ]
                                 },
                               ]
                 }";

 request.Method = "POST";
 request.ContentType = "application/json";

 using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
 {
 streamWriter.Write(args);
 streamWriter.Flush();
 streamWriter.Close();
 }

 WebResponse response = request.GetResponse();
 // ******************************************************************************************************
 // Print output to console
 Stream dataStream = response.GetResponseStream();
 StreamReader reader = new StreamReader(dataStream);
 string strResponse = reader.ReadToEnd();

 Console.WriteLine(strResponse);
 }
 }

Node JS

Save your script with the extension .js and run it using

 node scriptName.js

Script:

 // Replace with appropriate code snippet and API key
 // This will work for POST and PUT requests
 // Make sure to include the lines outputting JSON response, annotated below as "INCLUDE"
 // ******************************************************************************************************
 const https = require('https');

 var options = {
   "method": "POST",
   "hostname": "api.samplicio.us",
   "port": 443,
   "path": "/Demand/v1/Feasibility/Price?key={{API_key}}",
   "headers": {'Content-Type': 'application/json'}
 };

 var json = {"CountryLanguageID": 9, "LengthOfInterview": 5, "Incidence": 100, "Quotas": [{"CompletesPerDay": [1000, 1500], "Conditions": [{"QuestionID": 42, "PreCodes": ["18", "19", "20", "21", "22", "23", "24",
  "25", "26", "27", "28", "29"]}, {"QuestionID": 43, "PreCodes": ["1"] } ] }, ] };

 var params = JSON.stringify(json);

 var request = https.request(options, function (response) {
   var chunks = [];

   response.on("data", function (chunk) {
     chunks.push(chunk);
       //INCLUDE: at the end of stream
   }).on('end', function() {
       //INCLUDE: concatenate chunks into one string
   body = Buffer.concat(chunks).toString();
       //INCLUDE: print string to console
   console.log(body);
       //INCLUDE: close bracket
 });
 });

 request.write(params);

 request.end();
 // ******************************************************************************************************

Contributors

This project was built by the Fulcrum Tech Ops team.

Thanks to the following people who have submitted major pull requests:

nurbek-sozoev/developer-documentation

Developer Documentation

Table of Contents

Contributing

Style Guide

General

Resources

Endpoints

Example Code Snippets

GET

POST

PUT

DELETE

Guides

Building and Deploying Locally

Prerequisites

Setting up Prerequisites on Windows

Running the Project

Building and Deploying to Production

Testing API code snippets

curl

Ruby

PHP

Python

C#

Node JS

Contributors

Special Thanks