sk-api 1.0.6 → 1.1.0

data/README.rdoc

@@ -1,11 +1,9 @@
 = SalesKing Api
 
-This plugin is used internally by SalesKing to deliver the API and 
-can be used externally as an API client. The code is used in production at
-https://www.SalesKing, http://texprovider.de and http://planio.de
+This gem provides an api client using ActiveResource and also provides the API's JSON-Schema
+In the near future this will be decoupled and you will find links to the new gems here.
 
-The SalesKing API client uses ActiveResource, with some fixes due to json parsing.
-For now it only supports JSON, XML comes later.
+The SalesKing API client uses JSON and ActiveResource, with some fixes due to json parsing.
 
 To be able to use the API you must have an SalesKing account and API access. 
 Than you can start writing your own middelware-stack.
@@ -17,13 +15,209 @@ and support.
 
     gem install sk-api
 
-== Example
+Use with bundler
 
-	client = SkApi::Resources::Client.new(:last_name=>'Eder')
-	client.first_name = "Meister"
-	client.save
+    gem "sk-api", :require => 'sk_api'
+
+== Usage
+
+SalesKing's api interface is RESTful(mostly) and returns & accepts JSON data.
+All resources such as clients, invoices, products can be accessed via URL's
+through standard HTTP methods GET, POST, PUT and DELETE.
+
+To give it quick shot, point your browser to my-account.salesking.eu/api/clients.json
+(while beeing logged in) and you will see the JSON in the response.
+This is an example of a GET-request issued by your browser.
+
+<b>Request Method overview:</b>
+GET => read
+POST => create new data
+PUT => update data
+DELETE => delete data
+
+Want to know more about REST style webservices?
+* http://en.wikipedia.org/wiki/Representational_State_Transfer
+* http://www.google.com/search?q=REST+site%3Awww.infoq.com
+
+=== Authentification & Safety
+
+Authentification is done with HTTP basic using your SalesKing login email and password.
+For a production environment it is advisable to create a user, per api
+client-software, and restrict his rights with our build in role-system.
+
+=== Toolz
+
+Since browsers do not support PUT/DELETE methods you can use CURL, a linux
+command-line http client, for testing. And of course any http library supporting
+http-basic-auth can be used.
+
+* JSONView  FF-Plugin - view json in firefox https://addons.mozilla.org/de/firefox/addon/10869/
+* JSONovich FF-Plugin -  https://addons.mozilla.org/de/firefox/addon/10122/
+* A java GUI REST client http://code.google.com/p/rest-client/
+
+=== GET / Show data
+
+Get a list of resources:
+    GET xy.salesking.eu/api/invoices
+
+Get a single resource
+    GET xy.salesking.eu/invoices/:id
+
+Using CURL
+
+  curl -u your@login-mail.com:password \
+  https://demo.salesking.eu/clients.json
+
+Returned JSON data for a listings, abbreviated:
+    {
+    "clients": [                    # array of resources => clients
+      { "client": {                 # a single resource
+        "number": "0800013", ..
+        "links":{}                  #links to actions for the resource (comming soon)
+      }, ...
+    ],
+    collection": {                  # information about the collection
+      "total_pages": 1,
+      "total_entries": 3,
+      "current_page": 1,
+      "per_page": 30
+    },
+    "links": {                      # links for the collection
+      "prev": "/api/clients?page=0",
+      "next": "/api/clients?page=2",
+      "self": "/api/clients?page=1"
+      }, 
+    }
+
+==== Filtering
+
+Filtering data can be achived by adding a filter parameter to the url. 
+
+All objects which can be tagged(clients, documents, products) can be filter by a tag param, taking one or multiple tags:
+    GET xy.salesking.eu/api/invoices?filter[tags]=Agentur
+    GET xy.salesking.eu/api/invoices?filter[tags]=Agentur Grafik
+    # find all objects without tags
+    GET xy.salesking.eu/api/invoices?filter[not_tagged]=1
+
+All objects have a q-search available. The fields to be searched in can be seen inside SalesKing, behind the search field above list.
+    GET xy.salesking.eu/api/invoices?q=0800013
+    GET xy.salesking.eu/api/invoices?filter[q]=0800013
+
+Document specific filters
+  # find all documents for a client
+  GET xy.salesking.eu/api/invoices?filter[client]=:client_id
+
+Client filter:
+  # find clients organisation or lastname starting with A
+  GET xy.salesking.eu/api/clients?filter[letter]=A
+
+=== POST / Create data
+
+To create a resource you can use the gem with its methods or make a POST request containing the json for a single resource.
+The JSON format can be seen in each of the resources: http://github.com/salesking/sk-api/tree/master/lib/resources/
+
+  POST https://my-sub.salesking.eu/invoices.json content-type application/json
+
+This a minimal json to create a draft invoice:
+
+  {"invoice": {
+    "due_days": 14,
+    "line_items": [
+      {
+          "quantity_unit": "Stuck",
+          "tax": 19,
+          "price_single": 0,
+          "position": 1,
+          "quantity": 21,
+          "description": "dep38usabq4Boxen kostenlos"
+      },
+      {
+        "quantity_unit": "Stuck",
+        "tax": 19,
+        "price_single": 0.042022,
+        "position": 2,
+        "quantity": 21,
+        "description": "dep38usabq4 Boxen"
+      }
+    ],
+    "title": "Dabei",
+    "client_id": "c5d5xIwZGr3R56abxfpGMl",
+    "address_field": "Wurst Bolle\nHalve-Hahn Alle 4711\n50733 Köln-Nippes"
+  }}
+
+Some quick hints on document creation:
+
+* The line items array does not need prefixes .. (sry little inconsistency here)
+* Dates are formatted like  <tt>yyyy-mm-dd 2010-09-08</tt>
+* <tt>"price_total": 0.88,  "price_tax": 0.167</tt> can be ommited are calculated by sk => read only
+* <tt>due_date</tt> if left out will be auto calculated from due days. If date and due date are given due_days are not taken into consideration.
+* <tt>status: draft</tt> is default, so can be omitted
+* <tt>client_id</tt> must be given as uuid of the client object
+* line items with quantity of 0 are kicked
+* If you create the doc as draft you can leave out any dates. When “opened” in salesking the date will be set and due date is calculated from due_days
+* If you create the invoice as "open" you must set a number(and date), by now there is no api method to get the next number.
+* The proposed workflow is to create the document as draft and continue (open/send/close) in SalesKing.
+
+
+For more information on how to use take a look into the tests/specs:
+
+http://github.com/salesking/sk-api/tree/master/spec/resources/
+
+=== PUT / Update data
+
+To Update a client:
+ 
+PUT ( application/json ) to ../api/clients/:id
+  {
+    'client': 
+    { 
+      'gender':'male',
+      'first_name': "Andrew"
+    }
+  }
+
+=== DELETE / kill data
+
+To delete a record simply issue a DELETE request to a resource url:
+
+    DELETE https://demo.salesking.eu/clients/:id
+
+== Ruby Example
+
+Since the sk-api gem provides a wrapper around the whole url/request stuff its
+pretty straight forward to use:
+
+    class SomeMiddleware
+      include SKApi::Resources
+
+      def initialize()
+        # init api connection => just an example depending on your code structure do it wherever you want
+        set_api_connection
+      end
+
+      def create_client(last_name)
+        # create a new client object
+        client = SKApi::Resources::Client.new(:last_name=> last_name)
+        # set more data
+        client.first_name = "Meister"
+        # save it, which also does the remote saving action
+        client.save
+      end
+
+      def set_api_connection
+        SKApi::Resources::Base.set_connection({
+          :site     => 'my_sub.salesking.eu',
+          :user     => 'demo@salesking.eu',
+          :password => 'password',
+          :format   => :json # symbol expected
+        })
+      end
+    end
+
+    ##### use it
+    a = SomeMiddleware.new
+    a.create_client('eder')
 
-For more information on how to use take a look into the specs.
 
 == Salesking API Resources
 
@@ -34,7 +228,10 @@ Right now the following resources are available:
 * products
 * credit_notes
 
-== Tests
+See classes here:
+http://github.com/salesking/sk-api/tree/master/lib/resources/
+
+== Tests / Specs
 
 To run the test you must insert some credentials into the spec helper. 
 We will gladly provide you with a test account on one of our development 

data/VERSION

@@ -1 +1 @@
-1.0.6
+1.1.0

data/lib/{activeresource_patches → patches/ar2}/base.rb

@@ -27,7 +27,7 @@ module ActiveResource
       end
     end
 
-    # Ooverridden to grab the data(= clients-collection) from json:
+    # Overridden to grab the data(= clients-collection) from json:
     # { 'collection'=> will_paginate infos,
     #   'links' => prev/next links
     #   'clients'=> [data], << what we need
@@ -37,15 +37,4 @@ module ActiveResource
       collection.collect! { |record| instantiate_record(record, prefix_options) }
     end
   end
-end
-
-# Force json decoding using Rufus
-module ActiveResource
-  module Formats
-    module JsonFormat
-      def decode(json)
-        Rufus::Json.decode(json)
-      end
-    end
-  end
 end

data/lib/{activeresource_patches → patches/ar2}/validations.rb

@@ -1,5 +1,5 @@
 module ActiveResource
-   
+
   module Validations
     # Validate a resource and save (POST) it to the remote web service.
     def save_with_validation
@@ -13,7 +13,7 @@ module ActiveResource
         errors.from_json(error.response.body)
       end
       false
-    end   
+    end
   end
 
   class Errors

data/lib/patches/ar3/base.rb

@@ -0,0 +1,23 @@
+module ActiveResource
+  # Overridden methods to suit SalesKing.
+  # Some changes might be kicked when AR 3.0 is out
+  class Base
+
+    # override ARes method to parse only the client part
+    def load_attributes_from_response(response)
+      if response['Content-Length'] != "0" && response.body.strip.size > 0
+        load( self.class.format.decode(response.body)[self.class.element_name] )
+      end
+    end
+
+    # Overridden to grab the data(= clients-collection) from json:
+    # { 'collection'=> will_paginate infos,
+    #   'links' => prev/next links
+    #   'clients'=> [data], << what we need
+    # }
+    def self.instantiate_collection(collection, prefix_options = {})
+      collection = collection[ self.element_name.pluralize ] if collection.is_a?(Hash)
+      collection.collect! { |record| instantiate_record(record, prefix_options) }
+    end
+  end
+end

data/lib/patches/ar3/validations.rb

@@ -0,0 +1,13 @@
+module ActiveResource
+  class Errors < ActiveModel::Errors
+    # Patched cause we dont need no attribute name magic .. and its just simpler
+    # orig version is looking up the humanized name of the attribute in the error
+    # message, which we dont supply => only field name is used in returned error msg
+    def from_array(messages, save_cache=false)
+      clear unless save_cache
+      messages.each do |msg|
+        add msg[0], msg[1]
+      end
+    end
+  end #Errors
+end

data/lib/resources/address.rb

@@ -16,7 +16,7 @@ module SKApi
            "id"       => {"type" => "string", "identity" => true, "readonly" => true},
            "address1" => {"type" => "string", "optional" => true},
            "address2" => {"type" => "string", "optional" => true},
-           "city"     => {"type" => "string", "optional" => true},
+           "city"     => {"type" => "string"},
            "country"  => {"type" => "string", "optional" => true},
            "state"    => {"type" => "string", "optional" => true},
            "zip"      => {"type" => "string", "optional" => true},

data/lib/resources/client.rb

@@ -13,7 +13,7 @@ module SKApi
 
       def self.schema_props
        {
-           "id"           => {"type" => "string", "identity" => true , "readonly" => true},
+           "id"           => {"type" => "string", "identity" => true, "optional" => true, "readonly" => true},
            "number"       => {"type" => "string", "optional" => true},
            "organisation" => {"type" => "string"},
            "first_name"   => {"type" => "string", "optional" => true},
@@ -45,7 +45,7 @@ module SKApi
            "created_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
            "updated_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
            "address_field"  => {"type" => "string", "optional" => true, "readonly" => true},
-           "addresses"      => {"type" => "array"},
+           "addresses"      => {"type" => "array","properties" => SKApi::Resources::Address.schema_props, "optional" => true}
          }
       end #schema_props
 

data/lib/resources/invoice.rb

@@ -6,6 +6,19 @@ module SKApi
         save_with_validation
       end
 
+      def open
+        self.put(:open, :id => self.id)  # PUT /invoices/:id/open
+      end
+
+      # rethink
+      def print(template_id)
+        self.get(:print, :template_id => template_id)  # GET /invoices.pdf?template_id=:ids
+      end
+
+      def mail(template_id, cc, bcc)
+        self.get(:print, :template_id => template_id)  # GET /invoices.pdf?template_id=:ids
+      end
+
       ##########################################################################
       # Class methods
       ##########################################################################
@@ -41,8 +54,14 @@ module SKApi
 
       def self.api_links
         #internal links on fields=> id => salesking.eu/clients/4567.json
-      #external links to actions and related objects => invoeis => salesking.eu/clients/4567/invoices.json
         [:edit, :destroy, :copy, :print, :show, :payments, :payment_new]
+#        [ :edit,
+#          :destroy,
+#          { :copy =>"invoices/new?source=#{self.id}" },
+#            :open => "PUT invoices/#{self.id}/open",
+#            :print,
+#            :show, ]
+
       end
     end
   end

data/lib/resources/product.rb

@@ -22,7 +22,6 @@ module SKApi
            "quantity_unit"=> {"type" => "string", "optional" => true},
            "tag_list"     => {"type" => "string", "optional" => true},
            "lock_version" => {"type" => "integer", "readonly" => true, "optional" => true},
-           "published_at" => {"type" => "string", "format" =>"date", "optional" => true},
            "created_at"   => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true },
            "updated_at"   => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true },
          }

data/lib/sk_api.rb

@@ -1,29 +1,28 @@
-require 'rubygems'
+#require 'rubygems'
 require 'active_resource'
+require 'active_resource/version'
 # patches are for specific AR version
-#gem 'activeresource' , '=2.3.4'
+# switch A-resource patch includes
 
-unless RUBY_PLATFORM =~ /java/
-  require 'yajl'
-  require 'rufus-json'
-  Rufus::Json.backend = :yajl
-else
-  require 'json'
-  require 'rufus-json'
-  Rufus::Json.backend = :json
+if ActiveResource::VERSION::MAJOR == 3
+  require 'patches/ar3/base'
+  require 'patches/ar3/validations'
+elsif ActiveResource::VERSION::MAJOR < 3
+  require 'patches/ar2/validations'
+  require 'patches/ar2/base'
 end
 
 # utilities
-require File.dirname(__FILE__) + '/utils/field_map'
-require File.dirname(__FILE__) + '/utils/serializer'
+require 'utils/field_map'
+require 'utils/serializer'
 
 #resources
-require File.dirname(__FILE__) + '/activeresource_patches/validations'
-require File.dirname(__FILE__) + '/activeresource_patches/base'
-require File.dirname(__FILE__) + '/resources/base'
-require File.dirname(__FILE__) + '/resources/product'
-require File.dirname(__FILE__) + '/resources/client'
-require File.dirname(__FILE__) + '/resources/address'
-require File.dirname(__FILE__) + '/resources/invoice'
-require File.dirname(__FILE__) + '/resources/credit_note'
-require File.dirname(__FILE__) + '/resources/line_item'
+require 'resources/base'
+require 'resources/product'
+require 'resources/client'
+require 'resources/address'
+require 'resources/invoice'
+require 'resources/credit_note'
+require 'resources/line_item'
+
+# TODO before post kick empty fields and readonly's

data/lib/utils/serializer.rb

@@ -6,7 +6,7 @@ module SKApi
     # f.ex. in the clients api controller
     #   => SKApi::Resources::Client.to_json(a_client)
     # This way you can keep your API client up to date by using the resources and
-    # relying on  SKApi::Resources::Client.api_fields
+    # relying on  SKApi::Resources::Client.schema
     module Serializer
       def self.included(base)
         base.extend ClassMethods
@@ -42,8 +42,8 @@ module SKApi
                 # ex: data['invoice']['client'] = SKApi::Models::Client.to_hash_from_schema(client)
                 data[obj_class_name][field] = klass.to_hash_from_schema(rel_obj)
               end
-            else # a simple field which can be directly called
-              data[obj_class_name][field] = obj.send(field)
+              else # a simple field which can be directly called, only added of objects know its
+              data[obj_class_name][field] = obj.send(field) if obj.respond_to?(field.to_sym)
             end
           end
           data
@@ -52,7 +52,7 @@ module SKApi
         def to_json(obj)
           data = self.to_hash_from_schema(obj)
 #          data[:links] = self.api_links
-          Rufus::Json.encode(data)
+          ActiveSupport::JSON.encode(data)
         end
 
       end #ClassMethods

data/sk-api.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sk-api}
-  s.version = "1.0.6"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Georg Leciejewski"]
-  s.date = %q{2010-04-16}
+  s.date = %q{2010-11-07}
   s.description = %q{Interact with SalesKing}
   s.email = %q{gl@salesking.eu}
   s.extra_rdoc_files = [
@@ -23,9 +23,11 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "init.rb",
-     "lib/activeresource_patches/README",
-     "lib/activeresource_patches/base.rb",
-     "lib/activeresource_patches/validations.rb",
+     "lib/patches/README",
+     "lib/patches/ar2/base.rb",
+     "lib/patches/ar2/validations.rb",
+     "lib/patches/ar3/base.rb",
+     "lib/patches/ar3/validations.rb",
      "lib/resources/address.rb",
      "lib/resources/base.rb",
      "lib/resources/client.rb",
@@ -53,7 +55,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/salesking/sk-api}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{Interact with SalesKing}
   s.test_files = [
     "spec/resources/client_spec.rb",
@@ -68,7 +70,7 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rspec>, [">= 0"])
     else
       s.add_dependency(%q<rspec>, [">= 0"])

data/spec/resources/client_spec.rb

@@ -1,4 +1,4 @@
-require "#{File.dirname(__FILE__)}/../spec_helper"
+require 'spec/spec_helper'
 
 describe SKApi::Resources::Client, "in general" do
 
@@ -59,9 +59,10 @@ describe SKApi::Resources::Client, "in general" do
     client = SKApi::Resources::Client.find(@client.id)
     # convert to json and read raw without activeresource assigning classes
     json = client.to_json
-    obj = Rufus::Json.decode(json)
+    obj = ActiveSupport::JSON.decode(json)
+#     puts obj['client']['organisation']
     lambda {
-      JSON::Schema.validate(obj,  SKApi::Resources::Client.schema)
+      JSON::Schema.validate(obj['client'],  SKApi::Resources::Client.schema)
     }.should_not raise_error
   end
 
@@ -83,6 +84,7 @@ describe SKApi::Resources::Client, "with addresses" do
     #setup test client to work with
     @client = SKApi::Resources::Client.new(:organisation=>'Second from testing API2',
                                             :addresses => [{ :zip => '50374', :city => 'Cologne' }] )
+
     @client.save
   end
 

data/spec/resources/credit_note_spec.rb

@@ -1,4 +1,4 @@
-require "#{File.dirname(__FILE__)}/../spec_helper"
+require 'spec/spec_helper'
 
 describe SKApi::Resources::CreditNote, "in general" do
 
@@ -25,11 +25,12 @@ describe SKApi::Resources::CreditNote, "in general" do
     }.should raise_error(ActiveResource::ResourceNotFound)
   end
 
-  it "should create a doc" do
+  it "should create a doc and use default before after text" do
     @doc.errors.should be_empty
+    @doc.notes_before.should_not be_empty
     @doc.new?.should be_false
   end
-
+ 
   it "should fail create a doc" do
     doc = SKApi::Resources::CreditNote.new()
     doc.save.should == false
@@ -44,12 +45,11 @@ describe SKApi::Resources::CreditNote, "in general" do
 
   it "should validate raw json object with schema" do
     doc = SKApi::Resources::CreditNote.find(@doc.id)
-#    doc.number.should=='23'
     # convert to json and read raw without activeresource assigning classes
     json = doc.to_json    
-    obj = Rufus::Json.decode(json)
+    obj = ActiveSupport::JSON.decode(json)
     lambda {
-      JSON::Schema.validate(obj,  SKApi::Resources::CreditNote.schema)
+      JSON::Schema.validate(obj['credit_note'],  SKApi::Resources::CreditNote.schema)
     }.should_not raise_error
   end