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!
<code>#This DOES NOT WORK https://u@mail.de:pass@demo.salesking.eu/api/conta... <br># 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':[..] }<br><strong></strong>Index URL's return aditional information about the collection, links and of course the resources.
{ 'contacts':[..], 'links':[..], 'collection' :{..} }<br><strong></strong>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.herokuapp.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!