= SalesKing API Schema

Our API definition is using JSON Schema(http://json-schema.org/). A schema
describes a resource in terms of available fields, CRUD actions and
relationships with other resources.

For ruby users this project provides a gem with some basic utility functions
besides the schema. 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/

== 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.

The gem has its own version number. It is used by SalesKing to deliver it's
resources BUT changes might not be directly reflected. To see what version of
the gem we are using go to:

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

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.

You can get the current schema at your SalesKing api url:
  my.salesking.eu/api/schema
  my.salesking.eu/api/clients/schema

The schema 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'

== Save the planet

By default the api returns an object with all available properties(fields). You
can limit those by passing an array or comma-separated string 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!

== ToDo:

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

== Install

    gem install sk_api_schema

== Test

Before you run the tests use bundler to install all required gems:
  # git clone
  # cd into sk_api_schema dir
  BUNDLE_GEMFILE=ci/Gemfile bundle install
  BUNDLE_GEMFILE=ci/Gemfile bundle exec rake spec

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