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):
-
activesupport
-
activeresource
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.
Available resources, properties and links¶ ↑
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
¶ ↑
-
It sucks!
-
Most of the magic is coming from
ActiveResource
so you should read its README and code -
This client does NOT rely on parsing the JSON Schema, since ActiveResource(AR) creates the Getter/Setter methods.
-
We added some patches for AR to fix JSON parsing issues, due to our nesting.
-
non-restful routes can be accessed by custom methods see examples in AR
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.
-
Poster FF-Plugin - make HTTP request (you must be logged into SalesKing)
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