sk_api_schema 0.5.0 → 0.6.0

data/{CHANGELOG.rdoc → CHANGELOG.md}

@@ -1,12 +1,21 @@
-= Changelog for SalesKing API Schema
+# Changelog for SalesKing API Schema
 
 A more detailed view of the changes can be found in the {commit messages}[https://github.com/salesking/sk_api_schema/commits/]
 
-2012-11
+2013-01
+* add new item types: devider_item, sub_total_item
+* add items for documents containing all items by type
+* add filter\[tags] to products, mark price as required
+* add name-key to all objects containing the lowercased_underscored-name, PLEASE start using it instead of the title-field, which will be changed to its CamelCasedObjectName
+
+2012-12
+* add search filter to pdf_template, email_template
+* filter clients by ids - search for a list of comma separated uuids
 
-  * add currency fields for documents, client, company and payment
-  * add PDF template resource
-  * drop 'method' from payment in favour of payment_method
+2012-11
+* add currency fields for documents, client, company and payment
+* add PDF template resource
+* drop 'method' from payment in favour of payment_method
 
 2012-07
 * maxLength for all string properties with limits
@@ -51,9 +60,9 @@ A more detailed view of the changes can be found in the {commit messages}[https:
 
 2011-6
 * added language field to document, client, email-template
-* added filter[languages] for documents and clients, to search by one or more languages
-* added filter[client_ids] to documents, to search by one or multiple clients
-* added filter[ids] for documents, to find multiple specific documents
+* added filter\[languages] for documents and clients, to search by one or more languages
+* added filter\[client_ids] to documents, to search by one or multiple clients
+* added filter\[ids] for documents, to find multiple specific documents
 * changed _delete property to _destroy for address, line_item
 * removed client_id requirement for documents
 

data/json/v1.0/address.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "address",
+  "name": "address",
   "description":"An address in SK is maintained within it's parent object(client, company). The first address(default_address) is used inside the address field of new documents. With multiple addresses sorting(first) is done by date, newest first. So if you add a new adddress it will be the new default one. See order and type property for details about ordering and accessing parcel work or home addresses.",
   "properties":{
     "id":{

data/json/v1.0/attachment.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "attachment",
+  "name": "attachment",
   "description":"An file attachment",
   "properties":{
     "id":{

data/json/v1.0/auth_permission.json

@@ -1,5 +1,6 @@
 {"type":"object",
   "title": "auth_permission",
+  "name": "auth_permission",
   "description": "A Permission authorises someone to execute actions(grants privileges) in the scope of a context. The context is a resource f.ex: clients, and the privileges a group of actions like: index, show, edit, update. A permission to read invoices has the context: invoices and as privileges: index,show.",
   "properties":{
     "id":{

data/json/v1.0/client.json

@@ -1,5 +1,6 @@
 {"type":"object",
   "title": "client",
+  "name": "client",
   "description": "A client as seen by SalesKing",
   "properties":{
     "id":{
@@ -213,6 +214,11 @@
           "description": "Filter by a space delimited list of tags",
           "type":"string"
         },
+        "filter[ids]":{
+          "title" : "Clients",
+          "description": "A single or a list of client uuids, comma separated",
+          "type" : "string"
+        },
         "filter[created_at_from]":{
           "title" : "From date",
           "description": "Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",

data/json/v1.0/comment.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "comment",
+  "name": "comment",
   "description":"An comment in SK must always be related to an object.",
   "properties":{
     "id":{

data/json/v1.0/company.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "company",
+  "name": "company",
   "description": "A company is the main entity, so any data belongs to a company. It is identified by the current subdomain and cannot be edited via API atm",
   "properties":{
     "id":{

data/json/v1.0/credit_note.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "credit_note",
+  "name": "credit_note",
   "description": "A credit note",
   "properties":{
     "id":{

data/json/v1.0/divider_item.json

@@ -0,0 +1,42 @@
+{ "type":"object",
+  "title": "divider_item",
+  "name": "divider_item",
+  "description": "A divider item serves as a separator or headline between line items, e.g. to distinguish hardware and service products on a document. Access and creation is done via documents.items(instead of line_items) where each item has a 'type' field set to its CamelCased class name.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "position":{
+      "description": "Required since items are sorted by position.",
+      "type":"integer",
+      "required":true
+    },
+    "name":{
+      "description": "The divider text",
+      "type":"string",
+      "maxLength": 50
+    },
+   "created_at":{
+      "description": "Date the object was created in SK. Never changes afterwards",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "updated_at":{
+      "description": "Date the object was edited in SK.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "_destroy":{
+      "description": "When set an existing item will be deleted. This switch is used for items submitted nested within their parent object(a document), which is default as long as there is no line item endpoint available.",
+      "type":"boolean"
+    }
+  },
+  "links":[]
+}

data/json/v1.0/document.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "document",
+  "name": "document",
   "description": "This resource is readonly and serves as a convenient way to query documents independent of their type(invoice, order,..). The specific document type is set in each object in the result-set. Internally Document is the base class for all types and special fields are defined in each child-class. Due to this some fields might be missing if you are using this meta-class in queries.",
   "properties":{
     "id":{
@@ -66,7 +67,16 @@
     "line_items":{
       "description": "Line items for the document",
       "type":"array",
-      "properties":{"$ref":"./line_items.json#properties"}
+      "items":{"$ref":"./line_items.json#properties"}
+    },
+    "items":{
+      "description": "Items for the document. Access items of all types including divider and sub_total items.",
+      "type":"array",
+      "default": "any",
+      "minItems": 0,
+      "items": [{ "$ref": "./line_item.json#properties"},
+                { "$ref":  "./divider_item.json#properties"},
+                { "$ref": "./sub_total_item.json#properties"}]
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",

data/json/v1.0/email.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "email",
+  "name": "email",
   "description":"An email in SK must always be related to an object. Receivers are limited to 5 per address field.",
   "properties":{
     "id":{

data/json/v1.0/email_template.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "email_template",
+  "name": "email_template",
   "description":"An email_template in SK",
   "properties":{
     "id":{
@@ -85,6 +86,16 @@
           "title" : "Sort",
           "enum":["ASC","DESC"],
           "description": "Sort the results in ASC or DESC"
+        },
+        "filter[q]":{
+          "title" : "Search wildcard",
+          "description": "Searches in name, subject, body",
+          "type":"string"
+        },
+        "filter[kind]":{
+          "title" : "Search by kind",
+          "description": "Kind of object this template can be used for: invoice, credit_note (singular lowercase classname)",
+          "type":"string"
         }
       }
     },

data/json/v1.0/estimate.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "estimate",
+  "name": "estimate",
   "description": "An estimate",
   "properties":{
     "id":{

data/json/v1.0/export.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "export",
+  "name": "export",
   "description":"An export in SK",
   "properties":{
     "id":{

data/json/v1.0/export_template.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "export_template",
+  "name": "export_template",
   "description":"An export_template in SK",
   "properties":{
     "id":{

data/json/v1.0/invoice.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "invoice",
+  "name": "invoice",
   "description": "An invoice",
   "properties":{
     "id":{
@@ -118,6 +119,15 @@
       "type":"array",
       "properties":{"$ref":"./line_item.json#properties"}
     },
+    "items":{
+      "description": "Items for the document. Access items of all types including divider and sub_total items.",
+      "type":"array",
+      "default": "any",
+      "minItems": 0,
+      "items": [{ "$ref": "./line_item.json#properties"},
+                { "$ref":  "./divider_item.json#properties"},
+                { "$ref": "./sub_total_item.json#properties"}]
+    },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
       "format":"date-time",

data/json/v1.0/language.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "language",
+  "name": "language",
   "description": "A language in SK can be assigned to documents, contacts and templates. When creating new documents, emails or PDF the language is used to select a specific template or language agnostic defaults. A language has many translations.",
   "properties":{
     "id":{

data/json/v1.0/line_item.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "line_item",
+  "name": "line_item",
   "description": "A line item for a document",
   "properties":{
     "id":{

data/json/v1.0/order.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "order",
+  "name": "order",
   "description": "An order",
   "properties":{
     "id":{

data/json/v1.0/payment.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "payment",
+  "name": "payment",
   "description":"An payment in SK must always be related to an object.",
   "properties":{
     "id":{

data/json/v1.0/payment_reminder.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "payment_reminder",
+  "name": "payment_reminder",
   "description": "A payment reminder",
   "properties":{
     "id":{

data/json/v1.0/pdf_template.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "pdf_template",
+  "name": "pdf_template",
   "description":"An PDF template. For now this is a read-only resource ONLY returning your own templates. It fits the most important use-case: A user can select a print template.",
   "properties":{
     "id":{
@@ -87,7 +88,7 @@
         },
         "filter[kind]":{
           "title" : "Search by kind",
-          "description": "Kind of object this template can be used for: invoice, order",
+          "description": "Kind of object this template can be used for: invoice, credit_note (singular lowercase classname)",
           "type":"string"
         }
       }

data/json/v1.0/product.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "product",
+  "name": "product",
   "description": "A product in SK",
   "properties":{
     "id":{
@@ -26,9 +27,14 @@
       "type":"string",
       "format":"text"
     },
+    "tag_list":{
+      "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
+      "type":"string"
+    },
     "price":{
       "description": "Net price of a single product",
-      "type":"number"
+      "type":"number",
+      "required":true
     },
     "tax":{
       "description": "Tax percentage for this product.",
@@ -89,6 +95,11 @@
           "description": "Search by exact number",
           "type":"string"
         },
+        "filter[tags]":{
+          "title" : "Tags",
+          "description": "Filter by a space delimited list of tags",
+          "type":"string"
+        },
         "sort_by":{
           "title" : "Sort by",
           "description": "Sort the results by the given field => number",

data/json/v1.0/recurring.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "recurring",
+  "name": "recurring",
   "description": "An recurring is used as an template for new invoices.",
   "properties":{
     "id":{

data/json/v1.0/sub.json

@@ -1,5 +1,6 @@
 {"type":"object",
   "title": "sub",
+  "name": "sub",
   "description": "Subscribe to push notifications(webhooks) about object livecycle events like new, update or delete. Only returns subscription for the current app, so you MUST be using oAuth. When a user removes your app its subs are also deleted. <br/>To register you must supply <br/>- callback_url: receives a base64 encode string containing a JSON object with the object in it's latest state, the user_id & subdomain, company_id, hmac-signed with your app secret.<br/>- channel: defining the event, made up of the SINGULAR object name and the action: invoice.delete, payment.new<br/> - register auth_permissions: An app MUST request non-api permissions f.ex.: clients:create. Perms(on company,app,user,team) are checked before any publishing, so if a user cannot create clients in the interface, his apps will not receive any callbacks.",
   "properties":{
     "id":{

data/json/v1.0/sub_total_item.json

@@ -0,0 +1,52 @@
+{ "type":"object",
+  "title": "sub_total_item",
+  "name": "sub_total_item",
+  "description": "A sub-total item shows a sum of the previous line items, e.g. to distinguish hardware and service costs on a document.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "position":{
+      "description": "Required since items are sorted by position.",
+      "type":"integer",
+      "required":true
+    },
+    "name":{
+      "description": "Title of the sub-total e.g. Hardware total",
+      "type":"string",
+      "maxLength": 50
+    },
+    "net_total":{
+      "description": "Net sub-total",
+      "type":"number",
+      "readonly":true
+    },
+    "gross_total":{
+      "description": "Gross sub-total",
+      "type":"number",
+      "readonly":true
+    },
+   "created_at":{
+      "description": "Date the object was created in SK. Never changes afterwards",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "updated_at":{
+      "description": "Date the object was edited in SK.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "_destroy":{
+      "description": "When set an existing item will be deleted. This switch is used for items passed-in nested inside their parent object(a document), which is default as long as there is no line item endpoint available.",
+      "type":"boolean"
+    }
+  },
+  "links":[]
+}

data/json/v1.0/tag.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "tag",
+  "name": "tag",
   "description":"A tag",
   "properties":{
     "id":{

data/json/v1.0/text_template.json

@@ -1,5 +1,6 @@
 { "type":"object",
   "title": "text_template",
+  "name": "text_template",
   "description":"An text_template in SK",
   "properties":{
     "id":{

data/json/v1.0/user.json

@@ -1,5 +1,6 @@
 {"type":"object",
   "title": "user",
+  "name": "user",
   "description": "A user as seen by SalesKing",
   "properties":{
     "id":{

data/lib/sk_api_schema/version.rb

@@ -1,7 +1,7 @@
 module SK
   module Api
     class Schema
-      VERSION='0.5.0'
+      VERSION='0.6.0'
     end
   end
 end

data/spec/sk_api_schema_spec.rb

@@ -144,7 +144,7 @@ end
 ################################################################################
 # virtual classes used in test
 class Invoice
-  attr_accessor :id, :title, :description, :number, :date, :due_date, :line_items, :client, :archived_pdf
+  attr_accessor :id, :title, :description, :number, :date, :due_date, :line_items, :client, :archived_pdf, :items
 end
 
 class LineItem

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sk_api_schema
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -104,7 +104,7 @@ extra_rdoc_files:
 files:
 - .gitignore
 - .travis.yml
-- CHANGELOG.rdoc
+- CHANGELOG.md
 - Gemfile
 - README.rdoc
 - Rakefile
@@ -115,6 +115,7 @@ files:
 - json/v1.0/comment.json
 - json/v1.0/company.json
 - json/v1.0/credit_note.json
+- json/v1.0/divider_item.json
 - json/v1.0/document.json
 - json/v1.0/email.json
 - json/v1.0/email_template.json
@@ -131,6 +132,7 @@ files:
 - json/v1.0/product.json
 - json/v1.0/recurring.json
 - json/v1.0/sub.json
+- json/v1.0/sub_total_item.json
 - json/v1.0/tag.json
 - json/v1.0/text_template.json
 - json/v1.0/user.json
@@ -153,7 +155,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4021308870819249197
+      hash: -3277987017950227307
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: