Documentation

  1. What is Sick Web Service?
  2. Quick Start Guide
  3. General API Parameter
  4. List of available API's
  5. How to use Sick Web Service API in your application

What is Sick Web Service?

Sick Web Service is a service to connect Sick Submitter with our Sick Wordpress plugin. But you could also use it to connect your application with Sick Submitter, or even your application with your another application. It is now capable on adding link and retrieving link.

Some example of the usage of Sick Web Service are:

  1. Connect Sick Submitter with your application
  2. Add generated links from your application automatically and make it available to your another application
  3. Automatically retrieve generated links and use it on your application

Back to top

Quick Start Guide

To use Sick Web Service, you will first need to create API Key. While we could also offer authentication with your username and password, we encourage you to use API Key as you have more control over your links. With API Key, you could control which profile you need to return the links. You are able to create more than one API Key, so you can targetting some profile to one application, and the other profile to another application. Manage your API Key here.

When you have your API Key, you can immediately use our API. Our API request URL is http://api.sickmarketing.com/api.php. Our API accept either GET or POST request. You can use POST request when you need to insert a big data. The API will always return JavaScript Object Notation (JSON) data type, JSON have a wide implementation ready so you shouldn't have a problem with it. PHP have built in JSON and some Javascript like jQuery can process the JSON data automatically on their AJAX request, which is suitable for your web application.

Let's try to create the request to retrieve links.

  1. First off, we will add our API Key to the request URL, if your API Key is 0cac53006cc1474ca6f9d41f817ad509, then the request URL will be:
    http://api.sickmarketing.com/api.php?api_key=0cac53006cc1474ca6f9d41f817ad509
  2. Now we need to provide the action we needed, if you want to retrieve links, you can use the get_link API. The request URL is now:
    http://api.sickmarketing.com/api.php?api_key=0cac53006cc1474ca6f9d41f817ad509&action=get_link
  3. The get_link API have some parameters you can add, so for example if you want to retrieve the 100 newest links since January 1, 2011, then the final request URL is:
    http://api.sickmarketing.com/api.php?api_key=0cac53006cc1474ca6f9d41f817ad509&action=get_link&start=2011-01-01+00:00:00&limit=100
  4. Now you will get the JSON string. You can process this JSON string and use it in your application.

Back to top

General API Parameter

This parameters is available in all API request

Parameter Description Accepted Value Required/Optional
api_key 32 characters string key created at API Key (32 characters string API key) Required or use authenticate
authenticate Authenticate API request by using login username and double hashed password, the password is hashed by md5 username:md5(md5(password)) Required or use api_key
action Requested action add_link | get_link | add_profile | get_profile | get_group Required
return The return data type (currently only support JSON) json Optional

Back to top

List of available API's

Add one or more link

Parameter Description Accepted Value Required/Optional
profile Profile name (string) | (array) Required
group Group name, will be created automatically if not exists and assign your profile with this group (string) | (array) Optional
(Required if you pass array)
type Link type (string) | (array)
accept either profile | bookmark | article | rss		 Required
url Link URL (string) | (array)
must be a valid URL		 Required
title Link title (string) | (array) Required
date Link inserted date (string) | (array)
must use the pattern YYYY-MM-DD HH:MM:SS		 Required
data Insert bulk link by using JSON array, example JSON string: 
[
	{
		"profile": "Profile Name",
		"group": "My Group",
		"type": "bookmark",
		"url": "http://www.my-bookmark-link.com",
		"title": "My Bookmark",
		"date": "2011-01-01 00:00:00"
	},
	{
		"profile": "Profile Name",
		"group": "My Group",
		"type": "article",
		"url": "http://www.my-article-link.com",
		"title": "My Article",
		"date": "2011-01-01 00:00:00"
	}
]

All parameters (profile, group, type, url, title and date) must present in the array. 		(JSON string) Required or use profile, group, type, url, title, date

Notes: The profile, type, url, title and date parameters must have the same array size (if use array instead of string), otherwise, it would return error and no link will be inserted.

Return: total inserted links

Possible error code:

  • INVALID_JSON: this error is returned when you use the data parameter and you didn't provide a valid JSON string
  • EMPTY_PROFILE: this error is returned when you didn't pass the profile paramater
  • EMPTY_TYPE: this error is returned when you didn't pass the type parameter
  • EMPTY_URL: this error is returned when you didn't pass the url parameter
  • EMPTY_TITLE: this error is returned when you didn't pass the title parameter
  • EMPTY_DATE: this error is returned when you didn't pass the date parameter
  • INVALID_DATE: this error is returned when you didn't pass a valid date, the date must be in YYYY-MM-DD HH:MM:SS format
  • INVALID_DATA_ARRAY: this error is returned when you use the data parameter and pass an invalid data array
  • EMPTY_PARAMETER: this error is returned when there is no parameter to process
  • INVALID_PARAMETER_COUNT: this error is returned when the number of profile, type, url, title and date parameters is not equal (you probably miss one parameter)

Example adding a link through GET request:

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=add_link&profile=Example+Profile&type=article&url=http%3A%2F%2Fwww.your-website.com%2Farticle&title=Example+Article&date=2011-01-01+00:00:00

Note: String passed for all parameter must be URL encoded if needed

Return JSON string:

{"status":"success","data":{"added_item":1}}

Example of an invalid paramater through GET request:

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=add_link&profile=Example+Profile&type=article&url=http%3A%2F%2Fwww.your-website.com%2Farticle&title=Example+Article

Note: We missed the date parameter

Return JSON string:

{"status":"error","error":"INVALID_PARAMETER_COUNT"}

Example adding multiple links through GET request:

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=add_link&profile[0]=Example+Profile&group[0]=Example+Group&type[0]=article&url[0]=http%3A%2F%2Fwww.your-website.com%2Farticle&title[0]=Example+Article&date[0]=2011-01-01+00:00:00&profile[1]=Example+Profile+2&group[1]=Example+Group+2&type[1]=profile&url[1]=http%3A%2F%2Fwww.your-website.com%2Fprofile&title[1]=Example+Profile+Page&date[1]=2011-01-02+00:00:00

Note: We passed an array, there is a limit of character for GET request, so when you need to add a big data, we encourage you to use POST request instead

Return JSON string:

{"status":"success","data":{"added_item":2}}

Retrieve links, each API Key might targeting only some profiles. Manage the profiles targetted by API Key here.

Parameter Description Accepted Value Required/Optional
start Start time/date (string) | (integer)
accept either YYYY-MM-DD HH:MM:SS pattern date or UNIX timestamp		 Optional
end End time/date (string) | (integer)
accept either YYYY-MM-DD HH:MM:SS pattern date or UNIX timestamp		 Optional
limit Limit the link returned by specified number (default to 2000) (integer) Optional
offset Offset of the link returned, use in conjunction with limit (default to 0) (integer) Optional
sort Sort by the newest or oldest links (default to the newest links) (string)
accept either newest | oldest		 Optional

Return: requested links

Possible error code:

  • NO_PROFILES_ASSIGNED: this error is returned when you use an API Key without any profile assigned, thus unable to return any link
  • ZERO_RESULTS: this error is returned when you didn't have any result for your links

Example retrieving 100 links since 2011-01-01 through GET request sorted by the newest:

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=get_link&start=2011-01-01+00:00:00&limit=100&sort=newest

Return JSON string (example):

{"status":"success","data":[{"url":"http:\/\/www.site1.com","title":"Site 1","time":1300251373},{"url":"http:\/\/www.site2.com","title":"Site 2","time":1300251387}]}

add_profile

Add profiles and groups

Parameter Description Accepted Value Required/Optional
name Profile name (string) Required
group Group name, when obmitted, will only add profile (string) Optional

Return: indicate status of each execution (add profile, add group and assign group)

Possible error code:

  • EMPTY_PROFILE_NAME: this error is returned when it is obmitted or passed an invalid profile name

Adding a profile

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=add_profile&name=Example+Profile&group=Example

Return JSON string (example 1):

{"status":"success","data":{"added_group":1,"added_profile":1,"assign_group":1}}

Return JSON string (example 2, group exists):

{"status":"success","data":{"added_group":1,"added_profile":0,"assign_group":1}}

Return JSON string (example 3, profile exists):

{"status":"success","data":{"added_group":0,"added_profile":1,"assign_group":1}}

Return JSON string (example 1, all exists):

{"status":"success","data":{"added_group":0,"added_profile":0,"assign_group":0}}

get_profile

Retrieve profiles with assigned group name.

Parameter Description Accepted Value Required/Optional
all Indicate whether to return all profiles or only profiles assigned to the API key, default to only profiles assigned (boolean) Optional
limit Limit the profile returned by specified number (default to 200) (integer) Optional
offset Offset of the profile returned, use in conjunction with limit (default to 0) (integer) Optional

Return: requested profiles

Possible error code:

  • ZERO_RESULTS: this error is returned when you didn't have any result for your profiles

Example retrieving 2 profiles through GET request:

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=get_profile&limit=2

Return JSON string (example):

{"status":"success","data":[{"name":"Example Profile","groups":["Example"]},{"name":"Example Article","groups":["Example"]}]}

get_group

Retrieve groups.

Parameter Description Accepted Value Required/Optional
all Indicate whether to return all groups or only groups assigned to the API key, default to only groups assigned (boolean) Optional
limit Limit the group returned by specified number (default to 200) (integer) Optional
offset Offset of the group returned, use in conjunction with limit (default to 0) (integer) Optional

Return: requested groups

Possible error code:

  • ZERO_RESULTS: this error is returned when you didn't have any result for your profiles

Example retrieving 2 groups through GET request:

Request URL:

http://api.sickmarketing.com/api.php?api_key={YOUR_API_KEY}&action=get_group&limit=2

Return JSON string (example):

{"status":"success","data":["Group 1","Group 2"]}

Back to top

How to use Sick Web Service API in your application

Here is an example in PHP to add multiple links through POST request using Sick Web Service API

<?php // Set the API configuration $api_url = "http://api.sickmarketing.com/api.php"; $api_key = "0cac53006cc1474ca6f9d41f817ad509"; // The data array, this is an example for the structure $data = array( array( "profile" => "Profiles", "group" => "Default", "type" => "profile", "url" => "http://www.my-profile.com/profile1", "title" => "My Profile 1", "date" => "2011-01-01 00:01:01" ), array( "profile" => "Profiles", "group" => "Default", "type" => "profile", "url" => "http://www.my-profile.com/profile2", "title" => "My Profile 2", "date" => "2011-01-01 00:05:06" ), array( "profile" => "Articles", "group" => "Default", "type" => "article", "url" => "http://www.my-article.com/article-name", "title" => "My Article Title", "date" => "2011-01-02 01:09:52" ) ); // Init the CURL $handle = curl_init(); curl_setopt( $handle, CURLOPT_CONNECTTIMEOUT, 5 ); curl_setopt( $handle, CURLOPT_TIMEOUT, 5 ); curl_setopt( $handle, CURLOPT_URL, $api_url); curl_setopt( $handle, CURLOPT_RETURNTRANSFER, true ); curl_setopt( $handle, CURLOPT_MAXREDIRS, 0 ); // We make use of User-Agent string to determine your application, make sure to set this correctly so we could identify your application curl_setopt( $handle, CURLOPT_USERAGENT, "My Application/1.0" ); curl_setopt( $handle, CURLOPT_HEADER, true ); curl_setopt( $handle, CURLOPT_POST, true ); curl_setopt( $handle, CURLOPT_POSTFIELDS, array( "api_key" => $api_key, "action" => "add_link", "data" => json_encode($data) ) ); $response = curl_exec( $handle ); if ( ! empty($response) ) { $header_length = curl_getinfo($handle, CURLINFO_HEADER_SIZE); $header = trim( substr($response, 0, $header_length) ); $body = trim( substr($response, $header_length) ); // We decode the JSON string as an associative array $return = json_decode($body, true); if ( $return["status"] == "success" ) { printf("Added %d links successfully", $return["data"]["added_item"]); } else { printf("An error occured: %s", $return["error"]); } } ?>

Back to top