SalesKing API Client - SK::SDK::Base

Easily access SalesKing resources in a RESTfull way with this ActiveResource based SalesKing API client.

Install

gem install sk_sdk

For bundler add this to the Gemfile

gem "sk_sdk"
# or directly require a used class
gem "sk_sdk", :require => "sk_sdk/base"

Dependencies (gems):

Authorization

This client should be used with an oAuth2 access_token. But you can still use HTTBasic Auth(username & password). For a quick start BasicAuth is definitely easier, but it is less secure since you cannot track which client is accessing your account and the client has the full rights of the user. So if someone gets your credentials he can log into your SalesKing account and do whatever you can!

For a production environment using HTTP BasicAuth you should create one user per api client and restrict his rights with our role-system!

Getting an access_token or checking is validity is not the scope of this library, it merely sets an AUTHORIZATION header if you added a token in the connection settings.

AUTHORIZATION: Bearer YourAccessToken

More on oAuth here:

Usage

SalesKing's api interface is RESTful(mostly) and returns & accepts JSON data. All resources such as clients, invoices, products can be accessed via URL's through standard HTTP methods GET, POST, PUT and DELETE.

All objects and their endpoints are described in a json schema. You should read it and especially take a look at the schema's link section, where you can find available endpoints(urls), their nesting and parameters.

Class creation

Your classes simply descend from SK::SDK::Base and you need to add connection settings(site URL+user+passwd). You MUST provide the full URL using the right protocol in the connection and remember we only support HTTPS:

https + SUBDomain + salesking url + /api
=>
https://my_company.salesking.eu/api

For convenience we check if your url ends in /api and add it if you forgot it!

Create a single class

require 'sk_sdk/base'

class Contact < SK::SDK::Base;end

# connection using BasicAuth
Contact.set_connection( {:site => 'https://my_sub.salesking.eu/api',
                       :user => 'my-users@login-email.com',
                       :password => 'password' })

contact = Contact.new(:last_name => 'Ding', :organisation => "Carpenters Inc.", :type=>'Client')
contact.first_name = "Bill"
contact.save

Create multiple classes at once

require 'sk_sdk/base'
module; King; end
%w[Contact Invoice Product LineItem SubTotalItem].each do |model|
  eval "class King::#{model} < SK::SDK::Base;end"
end

# connection using oAuth access token
SK::SDK::Base.set_connection( {:site => 'https://my_sub.salesking.eu/api',
                              :token => 'someAccessToken'})

invoice = Invoice.new
invoice.title = "Hosting 2011"
item = LineItem.new { :position=>1, :name => 'Daily Backup',
                      :quantity_unit=> 'Month', :quantity => 12,
                      :price_single => 10.00 }
invoice.line_items = [ item ]
invoice.status = 'open'
invoice.save

Quick start - Basic's

To give it quick shot, point your browser to my-account.salesking.eu/api/contacts.json (while beeing logged in) and you will see the JSON in the response. This is an example of a GET-request issued by your browser.

Or use CURL, if you prefer the command line:

curl -u your@login-mail.com:password \
https://demo.salesking.eu/api/contacts

Request Method overview:

GET => read
POST => create new data
PUT => update data
DELETE => delete data

Want to know more about REST style webservices?

GET / Show

A list of resources:

GET xy.salesking.eu/api/invoices

A single resource

GET xy.salesking.eu/api/invoices/:id

Returned JSON data for a listings, abbreviated:

{
"contacts": [                    # array of resources => contacts
  { "contact": {                 # a single resource
    "number": "0800013", ..
    "links":{}                  #links for the resource
  }, ...
],
collection": {                  # info on index pages
  "total_pages": 1,
  "total_entries": 3,
  "current_page": 1,
  "per_page": 30
},
"links": {                      # links for the collection
  "prev": "/api/contacts?page=0",
  "next": "/api/contacts?page=2",
  "self": "/api/contacts?page=1"
  },
}

Filtering

Filtering is achieved by using the url filter param. Following some examples. Available filters are defined in each json-schema's instances link (see invoices)

#Find objects by tags
GET xy.salesking.eu/api/invoices?filter[tags]=Agentur

# find all objects without tags
GET xy.salesking.eu/api/invoices?filter[exclude_tags]=Agentur Grafik

# q-wildcard search in several fields
GET xy.salesking.eu/api/invoices?filter[q]=0815&per_page=40

# find all documents for one or more contacts
GET xy.salesking.eu/api/documents?filter[contact_ids]=:id,:id

POST / Create

To create a resource make a POST request containing the json for a single resource.

Header: content-type application/json
POST https://my-sub.salesking.eu/api/invoices.json

{"invoice": {
  "title": "Your service subscription 2011",
  "line_items": [ {
    "line_item": {
        "quantity_unit": "Month",
        "tax": 19,
        "price_single": 10.23,
        "position": 1,
        "quantity": 12,
        "name": "SalesKing Bronze Account"
    }
  } ]
}}

PUT / Update

Header: content-type application/json
PUT /api/contacts/:id
{
  'contact':
  {
    'gender':'male',
    'first_name': "Andrew",
    'type': 'Client'
  }
}

DELETE

A DELETE request to a resource url deletes and returns the deleted object:

DELETE https://demo.salesking.eu/api/contacts/:id

Hints on ActiveResource

E.g calling the print method a a document:

Invoice.find('uuid').post(:print, :template_id => 'pdf-template-uuid')

Tutorials & Tools

Since browsers do not support PUT/DELETE methods you can use CURL(a linux command-line http client) for testing. And of course any http library supporting http-basic-auth.

Tests / Specs

Please read the tests as they provide some more examples especially those in spec/resources

Run the specs with:

rake coverage

Copyright © 2011 Georg Leciejewski, released under the MIT license