Developer Documentation

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

Production Site

Table of Contents

1. Contributing
2. Style Guide
3. Building and Deploying Locally
4. Building and Deploying to Production

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

1. Resource title: Predefined in nav structure. If you are adding a new resource, reference the object in simple terms.
2. Resource description: 1 to 2 sentences describing the functionality of the endpoint in plain, non-industry specific language.
3. 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).
4. 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

1. 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.
2. Endpoint description: 1 to 2 sentences describing the functionality of the endpoint in plain, non-industry specific language.
3. 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.
4. 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.

1. Definition: {verb}{space}{url} Keep capitalization from old documentation.
2. 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.
3. 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}')

C#

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)

C#

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)

C#

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}')

C#

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": "stg-api.samplicio.us",
  "port": 443,
  "path": "/Demand/v1/SupplierAllocations/Delete/66900/196?key=8347B8DE-CE84-41C2-9D88-4503A7EFCAD8",
  "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.)

1. Install Ruby — Be sure to check "Add Ruby executables to your PATH".
2. Test the Ruby installation — Run ruby -v and irb -v in Command Prompt. If the version number is returned, Ruby has been successfully installed.
3. 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
4. Install other dependencies with the following commands:
   • gem install middleman-gh-pages
   • gem install bundler
5. 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
6. 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

1. Clone the repository to your hard drive with git clone {url}
2. cd developer documentation
3. Install all dependencies: bundle install
4. 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.

1. git checkout master
2. git pull origin master
3. rake publish

Contributors

This project was built by the Fulcrum Tech Ops team.

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

• @AmbyrShae
• @jurraca
• @Gulkinator
• @nikheintzen
• @brenankeller

Special Thanks

• Charlemagne3
• csampson
• mshwery
• dvillega
• Slate