Our API (objects,resources) is described with JSON Schema (json-schema.org).
See our API Browser for a visual presentation.
Each Object has its own description, with those top-level keys:
{
"type": "contact", // object type
"properties": { .. }, // field descriptions
"links": [ .. ] // CRUD actions, relationships to other resources
}
Look into the /json/ folder for the resources schema-files - github.com/salesking/sk_api_schema/tree/master/json/v1.0
For ruby pirates this project is available as gem. It provides some utility methods to read the schema files and convert objects to their schema notation. See /lib/sk_api_schema.rb
Other languages should take advantage of the raw json files.
Primary object types in SK are:
-
Documents
-
Contacts
-
Products
Secondary objects, tied to a primary(related) object
-
Attachments
-
Comments
-
Messages
-
Tags
Supportive objects
-
Company
-
Users
-
Exports
-
Templates
Following list gives you a quick overview of relations with nested urls an how parameters work. You can find those in detail when looking at the link section of each schema.
# GET invoices tagged with hosting and important /invoices?filter[tags]=important,hosting # GET orders for given contact ids /orders?filter[contact_ids]=:contact_id,:contact_id # GET products second page with 100 in list, only id+name /products?per_page=100&page=2&fields=id,name # all comments for an invoice /invoices/:id/comments # all documents of a contact /contacts/:id/documents # all invoices of a contact /contacts/:id/contact
Most of the fields are of type ‘string’. Their format(espacially date fields) is casted on our side. We try to go with the formats and types defined by JSON-Schema
All text MUST be UTF-8 encoded.
Some example fields:
"title":{
"description": " Cut-off after 255 Characters",
"type":"string",
"maxLength": 255
},
"notes_before":{
"description": "Long Text is a custom format: see notes below",
"type":"string"
"format":"text"
},
"net_total":{
"description": "Number with 2 decimals places",
"readonly":true,
"type":"number"
},
"status":{
"description": "Allowed values are in enum list",
"default":"draft",
"enum":["draft","open","closed","rejected","billed" ],
"type":"string"
},
"created_at":{
"description": "Date time ISO 8601 format: YYYY-MM-DDThh:mm:ssZ",
"format":"date-time",
"readonly":true,
"type":"string"
},
Text-Format length varies, between ~16,000 to 65.535, with the occurence of non-ASCII Characters see this post on stackoverflow
The main API-version is kept in the folder-name and as long as there are no major changes(breaking backwards compatibility), the version number will remain.
You can see the current schema at:
my.salesking.eu/api/schema my.salesking.eu/api/contacts/schema
The schema main version(NOT the gem version) can be set with the “v” url parameter in any call, but is pretty useless as long as we are in v1.0
my.salesking.eu/api/contacts?v='1.0'
The gem has its own version number. A new gem version indicates a change, but we first try it on our staging environment before any live instances are updated and the schema becomes public available. The gem is used by SalesKing to deliver it’s data BUT changes might not be directly reflected as stated. To see the current gem version use:
my.salesking.eu/api/schema?gem_version=1
By default the API returns an object with all available properties(fields). You can limit those by passing comma-separated string(or array) in the fields parameter:
my.salesking.eu/api/contacts?fields=id,organisation my.salesking.eu/api/contacts?fields[]=id&fields[]=organisation
Please try to only request the fields you really need, to save computing power!
gem install sk_api_schema
Tested with travis-ci, but of course you can run them too. Install required gems with bundler and go for it:
# git clone # cd into sk_api_schema dir bundle install rake spec
Copyright © 2010-2016 Georg Leciejewski, released under the MIT license