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/…
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!
# Use THIS instead
curl --user email@example.com: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.
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.
A resource is returned as json string with the resource nested beneath its name and a link section.
Index URL’s return aditional information about the collection, links and of course the resources.
Nested related objects are also prefixed with their object type and have a link section.
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
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?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:
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.
[ "to_addr", "can't be blank" ],
["body", "can't be blank" ],
All string input MUST be UTF-8 encoded!!! We do not convert anything!
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:
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/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:
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!