= SalesKing API Schema

Our API is described with JSON Schema's (http://json-schema.org), describing our objects(resources) in a readable JSON format:

  {
    "title": "client",
    "properties": { ...},
    "links": [ .. ]
  }
The properties-section defines the fields. CRUD actions and
relationships with other resources are found in the link-section.

Look into the /json/ folder for the resources schema-files - https://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}[https://github.com/salesking/sk_api_schema/blob/master/lib/sk_api_schema.rb]

Other languages should take advantage of the raw json files.

== Tutorial & Docs

* {API Browser visualized JSON Schema}[http://sk-api-browser.heroku.com/]
* {API Intro}[http://dev.blog.salesking.eu/api/]
* {Ruby SDK - API Client}[https://github.com/salesking/sk_sdk]

== Versioning

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/clients/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/clients?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

== Save the planet

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/clients?fields=id,organisation

  my.salesking.eu/api/clients?fields[]=id&fields[]=organisation

Please try to only request the fields you really need, to save computing power!

== Object Basic's

Primary object types in SK are:
* Documents
* Contacts
* Products

Secondary objects are always tied to a primary(related) object
* Attachments
* Comments
* Messages
* Tags

The third kind are supportive objects
* Company
* Users
* Exports
* Templates

== Endpoints & Links

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 client ids
    /orders?filter[client_ids]=:client_id,:client_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 client
    /clients/:id/documents

    # all invoices of a client
    /clients/:id/invoices

== Install

    gem install sk_api_schema

== Test

{<img src="https://secure.travis-ci.org/salesking/sk_api_schema.png?branch=master" alt="Build Status" />}[http://travis-ci.org/salesking/sk_api_schema]

Install required gems with bundler and go for it:
  # git clone
  # cd into sk_api_schema dir
  bundle install
  rake spec


== ToDo:

Those relative urls in the link sections, need some love, so please don't rely on
them to much right now.

Copyright (c) 2010-2012 Georg Leciejewski, released under the MIT license