27. January 2011 / by Georg Leciejewski

API Documentation

Our API is RESTful (mostly) using JSON for transport. The data-format is defined by a JSON-Schema, providing human and machine readable object descriptions.

Getting started

To take a quick dive, please use Google Chrome and the cREST-Extension, while being logged-on. You can start instantly by using your api-url https://my-account.salesking.eu/api/…

Impatient?

Authentication

You can still use HTTP BASIC Auth using your normal email/password combination. Make sure to properly base64 encode the auth-header since the username(email) contains a special character!

#This DOES NOT WORK
https://u@mail.de:pass@demo.salesking.eu/api/contacts
# Use THIS instead
curl --user u@mail.de:pass https://demo.salesking.eu/api/contacts

oAUTH2 in combination with SalesKing Apps are also available, but still in beta. Please email us so we can provide you with this function.

Resources

The pluralized object name leads to the resource list, appending an object.id returns a single resource. Nesting is possible where it makes sense and you can find the available links in each object.

api/contacts
api/contacts/:id
api/contacts/:id/invoices
api/contacts/:id/invoices

A resource is returned as json string with the resource nested beneath its name and a link section.

{ 'contact':{..}, 'links':[..] }

Index URL’s return aditional information about the collection, links and of course the resources.

{ 'contacts':[..], 'links':[..], 'collection' :{..} }

Nested related objects are also prefixed with their object type and have a link section.

{'contact':{ 'addresses': [{ 'address':{..} , 'links':[..] }] }}

Some constrains for now:

  • Comments, emails and payments are created beneath their parents path: POST /orders/:id/comments, /contacts/:id/emails
  • LineItems and addresses dont have an endpoint yet and can only be handled nested inside their parents json

Parameter

Some endpoint methods allow the use of additional parameter, f.ex to filter lists, and can be found in the links section of each json-schema.
Popular params are: q => searching lists, per_page => how many to show on a page, fields => restrict returned fields

api/contacts?q=osa #wildcard search in contacts number, first,last-name, organisation, email
api/contacts?per_page=30 #show 30 results per page
api/contacts?fields=id,number # only returns those fields in each record

Status Codes, Errors

HTTP-status codes are the first thing to be checked:

422 Unprocessable Entity - create/update-fails
403 Forbidden - destroy failed
401 unauthorized - not logged in or restricted by roles
404 page not found

Errors on object properties(edit/create) are returned as array. Each entry consisting of the property name and an error message. Errors on nested objects(line_items) are prefixed with their object name.

{
"errors": [
[ "to_addr", "can't be blank" ],
["body", "can't be blank" ],
]
}

Encoding

All string input MUST be UTF-8 encoded!!! We do not convert anything!

Language

To get translated error messages and take advantage of other language related features, a language can be set.
The language defaults to the one used by the current user but can be overridden by a locale parameter:

/api/contacts?locale=de_DE

Schema & Versioning

Current version is 1.0. The main version, will get bug fixes and improvements, (hopefully) not braking backwards compatibility.
Our resource JSON-Schema’s are hosted on github.com, where you SHOULD follow the changes. Each resource has a /schema url returning the current schema. A version parameter can be added to every call.

/api/schema?v=1.0 # all schema's for the current or given version
/api/orders/schema # current orders schema

You should install a JSONview browser plugin or you can use our resource browser available here: http://sk-api-browser.heroku.com/

In case you are familiar with Ruby or Ruby-Gems you can use the sk_api_schema gem. We do the same internally. The gem_version-param shows our current internal version:

my.salesking.eu/api/schema?gem_version=true

Note

We are trying hard making our webservice fun to use, but since this is the first public main version, things will improve. Especially those points will be tackled:

  • more request header fields the RESTful way
  • revise object links – don’t rely on relative uri’s yet
  • more property constrains: min/max length
  • request limits

Please be nice!