sk_api_schema 0.0.18 → 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,26 @@
+= 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/]
+
+2011-04
+* added tags
+* added documents
+* reduced default objects in list to 10, max is 100
+* added field parameter to limit returned fields in ruby to_hash_from_schema & SK
+* added created_at & number filtering to client
+* added _delete field to line_item & address, to be able to destroy them since both are transfered within their parent object 
+
+2011-03
+* added subscriptions
+* added memoizing to ruby schema reader
+
+2011-02
+* added moneybookers, premium_sms to payment methods
+* added auth_permission
+* added external_ref to documents
+* added company
+* added recurring
+* added source param to copy documents
+
+2010-11 - 2011-01
+* initial version

data/README.rdoc

@@ -1,23 +1,28 @@
-= SalesKing Api Schema
+= SalesKing API Schema
 
-SalesKing API description using JSON Schema(http://json-schema.org/). A schema
-describes the resource in terms of available fields, CRUD actions and
+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 can take advantage of the raw json files.
+besides the schema. Other languages should take advantage of the raw json files.
 
 == Tutorial & Docs
 
-http://dev.blog.salesking.eu/api/
+* API Browser visualized JSON Schema - http://sk-api-browser.heroku.com/
+* API Intro - http://dev.blog.salesking.eu/api/
 
 == Versioning
 
-The API-version is kept in the folder-name and as long as there are no major
+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.
+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.
 
@@ -25,9 +30,19 @@ You can get the current schema at your SalesKing api url:
   my.salesking.eu/api/schema
   my.salesking.eu/api/clients/schema
 
-The version to use can be set with the "v" url parameter:
+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!
 
 == Notice:
 

data/VERSION

@@ -1 +1 @@
-0.0.18
+0.1.0

data/json/v1.0/address.json

@@ -40,7 +40,8 @@
     "created_at": {
       "description": "Date the object was created in SK. Never changes afterwards",
       "format":"date-time",
-      "readonly":true, "type":"string"
+      "readonly":true,
+      "type":"string"
     },
     "updated_at": {
       "description": "Date the object was edited in SK.",
@@ -60,6 +61,10 @@
     "long": {
       "description": "Geolocation longitude",
       "type":"string"
+    },
+    "_delete": {
+      "description": "When set an existing address will be deleted. This switch is only used when addresses are passed-in nested inside their parent object(a contact).",
+      "type":"boolean"
     }
   }
 }

data/json/v1.0/attachment.json

@@ -23,6 +23,16 @@
       "readonly":true,
       "type":"string"
     },
+    "related_object_type": {
+      "description": "Object type of the attachment parent. Is the camelcased base class name: Document for invoice, credit_note,.., Contact for client",
+      "required":true,
+      "type":"string"
+    },
+    "related_object_id": {
+      "description": "uuid of the attachment parent object.",
+      "required":true,
+      "type":"string"
+    },
     "content_type": {
       "description": "Auto detected on upload. Might not always reflect the real content type",
       "readonly":true,
@@ -43,16 +53,60 @@
       "readonly":true,
       "type":"string"
     },
-    "updated_at": {
-      "description": "Date the object was edited in SK.",
-      "format":"date-time",
-      "readonly":true,
-      "type":"string"
-    },
     "team_id":{
       "description": "A team uuid. If set only the team and its parent teams can see the record.",
       "type":"string"
     }
     
-  }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "attachments/{id}"
+    },
+    { "rel": "instances",
+      "href": "attachments",
+      "properties" : {
+        "page":{
+          "title" : "Page",
+          "description": "In paginated results set the page to look for",
+          "type":"number"
+        },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Search in filename",
+          "type":"string"
+        },
+        "filter[from]":{
+          "title" : "From date",
+          "description": "All objects created at and after the date",
+          "type" : "date"
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "All objects created at and before the date",
+          "type" : "date"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field",
+          "enum":["filename","related_object_id","related_object_type", "created_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "attachments/{id}",
+      "method": "DELETE"
+    }
+  ]
 }

data/json/v1.0/auth_permission.json

@@ -36,6 +36,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in name and context names",

data/json/v1.0/client.json

@@ -157,9 +157,14 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
-          "description": "Search in first, last_name, organisation, email, number",
+          "description": "Wildcard search in first, last_name, organisation, email, number",
           "type":"string"
         },
         "filter[tags]":{
@@ -167,13 +172,20 @@
           "description": "Filter by a space delimited list of tags",
           "type":"string"
         },
-        "filter[from]":{
+        "filter[created_at_from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",
+          "type" : "date-time"
         },
-        "filter[to]":{
+        "filter[created_at_to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",
+          "type" : "date-time"
+        },
+        "filter[number]":{
+          "title" : "By number",
+          "description": "Search by number where the number is matched from the start: %number",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",
@@ -200,6 +212,9 @@
       "href": "clients",
       "method": "POST"
     },
+    { "rel": "documents",
+      "href": "clients/{id}/documents"
+    },
     { "rel": "attachments",
       "href": "clients/{id}/attachments"
     },

data/json/v1.0/comment.json

@@ -52,6 +52,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in text",
@@ -59,11 +64,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/credit_note.json

@@ -90,7 +90,7 @@
     "line_items":{
       "description": "Line items for the document",
       "type":"array",
-      "properties":{"$ref":"./address.json#properties"}
+      "properties":{"$ref":"./line_item.json#properties"}
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
@@ -156,6 +156,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -168,11 +173,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" :"date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" :"date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/document.json

@@ -0,0 +1,157 @@
+{ "type":"object",
+  "title": "document",
+  "description": "This resource is readonly and serves as a convinient way to query documents independent of their type(invoice, order,..). The specific document type is set in each object in the result-set.",
+  "properties":{
+    "id":{
+      "description": "UUID assigned by SK",
+      "identity":true,
+      "readonly":true,
+      "type":"string"
+    },
+    "object_type":{
+      "description": "The specific type of the document",
+      "type":"string"
+    },
+    "number":{
+      "description": "Unique number assigned by SK user or object number schema.",
+      "type":"string"
+    },
+    "address_field":{
+      "description": "Receiver address, normally shown in envelope window. Defaults to client address_field.",
+      "type":"string"
+    },
+    "date":{
+      "description": "Date the docuent is issued. Automatically set when document is opened. Required for non-draft documents.",
+      "format":"date",
+      "type":"string"
+    },
+    "external_ref":{
+      "description": "Some external reference, whatever this may be.",
+      "type":"string"
+    },
+    "title":{
+      "description": "The headline of a document. Use SK placeholders to prevent exessive typing e.g. 'Your invoice [number]'",
+      "type":"string"
+    },
+    "notes_before":{
+      "description": "Notes shown before the line items. Normaly contains salutation and other introductional information. SK placeholders can be used.",
+      "type":"string"
+    },
+    "notes_after":{
+      "description": "Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.",
+      "type":"string"
+    },
+    "tag_list": {
+      "description": "Space separated list of tags.",
+      "type":"string"
+    },
+    "precision":{
+      "description": "Decimal places for displayed(printed) money values. gross_total and net_total will always be displayed rounded to a precision of 2. When greater 2 use net_total_base(also in line_item) to show the net val with the set precision(3,4).",
+      "type":"number",
+      "enum": [2,3,4],
+      "default":2
+    },
+    "client_id":{
+      "description": "The clients uuid",
+      "type":"string",
+      "required":true
+    },
+    "team_id":{
+      "description": "A team uuid. If set only the team and its parent teams can see the record.",
+      "type":"string"
+    },
+    "line_items":{
+      "description": "Line items for the document",
+      "type":"array",
+      "properties":{"$ref":"./line_items.json#properties"}
+    },
+    "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"
+    },
+    "gross_total":{
+      "description": "Gross total of all line items, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "tax_total":{
+      "description": "Tax total, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "net_total":{
+      "description": "Net total, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "net_total_base":{
+      "description": "Net total, decimals places as set in precision, default 2",
+      "readonly":true,
+      "type":"number"
+    },
+    "net_total_base_raw":{
+      "description": "Net total, 6 decimal places. Summmed items net_total_base_raw (incl discount)",
+      "readonly":true,
+      "type":"number"
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "documents/{id}"
+    },
+    { "rel": "instances",
+      "href": "documents",
+      "properties" : {
+        "page":{
+          "title" : "Page",
+          "description": "In paginated results set the page to look for",
+          "type":"number"
+        },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Search in title, number, addressfield",
+          "type":"string"
+        },
+        "filter[tags]":{
+          "title" : "Tags",
+          "description": "Filter by a space delimited list of tags",
+          "type":"string"
+        },
+        "filter[from]":{
+          "title" : "From date",
+          "description": "All objects with a date after the date",
+          "type" : "date"
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "All objects with date before the date",
+          "type" : "date"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["title", "number", "created_at", "updated_at", "client_id", "price_total", "price_tax", "date", "due_date"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC"
+        }
+      }
+    }
+  ]
+}

data/json/v1.0/email.json

@@ -92,6 +92,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in body and subject",
@@ -111,11 +116,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects updated on/after the date"
+          "description": "All objects updated on/after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects updated on/before the date"
+          "description": "All objects updated on/before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/email_template.json

@@ -58,6 +58,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "sort_by":{
           "title" : "Sort by",
           "description": "Sort the results by the given field => number",

data/json/v1.0/estimate.json

@@ -86,7 +86,7 @@
     "line_items":{
       "description": "Line items for the document",
       "type":"array",
-      "properties":{"$ref":"./address.json#properties"}
+      "properties":{"$ref":"./line_item.json#properties"}
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
@@ -142,6 +142,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -154,11 +159,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/export.json

@@ -85,14 +85,20 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
-       
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/export_template.json

@@ -57,6 +57,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "sort_by":{
           "title" : "Sort by",
           "description": "Sort the results by the given field => number",

data/json/v1.0/invoice.json

@@ -91,7 +91,7 @@
     "line_items":{
       "description": "Line items for the document",
       "type":"array",
-      "properties":{"$ref":"./address.json#properties"}
+      "properties":{"$ref":"./line_item.json#properties"}
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
@@ -157,6 +157,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -169,11 +174,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/line_item.json

@@ -44,7 +44,7 @@
       "required":true
     },
     "product_id":{
-      "description": "An item can reference a product. This makes it easier to track a products turnover and the documents it is used on. Also ee use_product",
+      "description": "A uuid of a product, referenced in this item. This makes it easier to track a products turnover and list the documents it is used on. Also see use_product",
       "type":"string"
     },
     "use_product":{
@@ -62,6 +62,10 @@
       "format":"date-time",
       "readonly":true,
       "type":"string"
+    },
+    "_delete": {
+      "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"
     }
   }
 }

data/json/v1.0/order.json

@@ -76,7 +76,7 @@
     "line_items":{
       "description": "Line items for the document",
       "type":"array",
-      "properties":{"$ref":"./address.json#properties"}
+      "properties":{"$ref":"./line_item.json#properties"}
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
@@ -132,6 +132,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -144,11 +149,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/payment.json

@@ -61,6 +61,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -68,11 +73,14 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
+
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/payment_reminder.json

@@ -81,7 +81,7 @@
     "line_items":{
       "description": "Line items for the document. Defaults to invoice.gross_total and late fee values from settings",
       "type":"array",
-      "properties":{"$ref":"./address.json#properties"}
+      "properties":{"$ref":"./line_item.json#properties"}
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
@@ -122,6 +122,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -134,11 +139,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/product.json

@@ -66,6 +66,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Searches in number, name, description, price",

data/json/v1.0/recurring.json

@@ -88,7 +88,7 @@
     "line_items":{
       "description": "Line items for the document",
       "type":"array",
-      "properties":{"$ref":"./address.json#properties"}
+      "properties":{"$ref":"./line_item.json#properties"}
     },
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards.",
@@ -144,6 +144,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "filter[q]":{
           "title" : "Search",
           "description": "Search in title, number, addressfield",
@@ -156,11 +161,13 @@
         },
         "filter[from]":{
           "title" : "From date",
-          "description": "All objects with a date after the date"
+          "description": "All objects with a date after the date",
+          "type" : "date"
         },
         "filter[to]":{
           "title" : "To date",
-          "description": "All objects with date before the date"
+          "description": "All objects with date before the date",
+          "type" : "date"
         },
         "sort_by":{
           "title" : "Sort by",

data/json/v1.0/tag.json

@@ -0,0 +1,63 @@
+{ "type":"object",
+  "title": "tag",
+  "description":"A tag",
+  "properties": {
+    "id": {
+      "description": "uuid of the object.",
+      "identity":true,
+      "readonly":true,
+      "type":"string"
+    },
+    "name": {
+      "description": "The tag itself",
+      "readonly":true,
+      "type":"string"
+    },    
+    "taggings_count": {
+      "description": "Usage count of this tag, for all objects in whole company scope.",
+      "readonly":true,
+      "type":"number"
+    }    
+  },
+  "links":[
+    { "rel": "self",
+      "href": "tags/{id}"
+    },
+    { "rel": "instances",
+      "href": "tags",
+      "properties" : {
+        "page":{
+          "title" : "Page",
+          "description": "In paginated results set the page to look for",
+          "type":"number"
+        },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Search in name",
+          "type":"string"
+        },
+        "filter[related_object_type]":{
+          "title" : "Related object type",
+          "description": "Filter tags by their related object base type",
+          "type":"string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field",
+          "enum":["filename","taggings_count"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC"
+        }
+      }
+    }
+  ]
+}

data/json/v1.0/text_template.json

@@ -53,6 +53,11 @@
           "description": "In paginated results set the page to look for",
           "type":"number"
         },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 10, max is 100",
+          "type":"number"
+        },
         "sort_by":{
           "title" : "Sort by",
           "description": "Sort the results by the given field => number",

data/lib/sk_api_schema.rb

@@ -1,5 +1,6 @@
 require 'active_support'
 require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/string/inflections'
 module SK
   module Api
     class Schema
@@ -9,23 +10,29 @@ module SK
         # class var remembering already read-in schema's
         # {
         #   'v1.0'=>{
-        #     'invoice'=>{schema}
-        #     'credit_note'=>{schema}
+        #     :invoice =>{schema}
+        #     :credit_note =>{schema}
         #   }
         # }
         # === Return
-        #<Hash>::
+        #<Hash{String=>Hash{Symbol=>HashWithIndifferentAccess}}>::
         def registry
           @registry ||={}
         end
+        
+        def registry_reset
+          @registry = nil
+        end
         # Read a schema with a given version and return it as hash
         # See ../json folder for available schema's and versions
         # === Parameter
         # schema<String|Symbol>::name of the schema, available ones are in json directory
-        # version<String>:: version to read, this is the folder name where the schema is in.
+        # version<String>:: version to read, the folder name where the schema is in.
+        # Can be used without v-prefix
         # === Return
         # <HashWithIndifferentAccess>:: schema as hash
         def read(schema, version)
+          schema = schema.to_sym
           return registry[version][schema] if registry[version] && registry[version][schema]
           # prefix version with v1.0 of v is not present
           v = (version =~ /^v/) ? version : "v#{version}"
@@ -33,7 +40,7 @@ module SK
           # read schema from file
           file_path = File.join(File.dirname(__FILE__), '../json', v, "#{schema}.json")
           plain_data = File.open(file_path, 'r'){|f| f.read}
-          # remember
+          # remember & return
           registry[v][schema] = ActiveSupport::JSON.decode(plain_data).with_indifferent_access
         end
 
@@ -41,46 +48,65 @@ module SK
         # them as array
         # See ../json folder for available schema's and versions
         # === Parameter
-        # schema<String|Symbol>::name of the schema, available ones are in json directory
+        # schema<String|Symbol>:: version to read, equals json/foldername v1.0 or
+        # use without prefix 1.0
         # === Return
         # Array[<HashWithIndifferentAccess>]:: array of schemas as hash
         def read_all(version)
           schemas = []
           v = (version =~ /^v/) ? version : "v#{version}"
+          registry[v] = {} unless registry[v]
           file_path = File.join(File.dirname(__FILE__), '../json', v, '*.json')
           Dir.glob( file_path ).each do |file|
-            schema = File.open(file, 'r'){|f| f.read}
-            schemas << ActiveSupport::JSON.decode(schema).with_indifferent_access
+            schema_name = File.basename(file, ".json").to_sym
+            schemas << read(schema_name, v)
           end
           schemas
         end
 
         # Create a Hash with the available (api)object attributes defined in the
-        # according schema properties. This is the meat of the object-to-api
-        # workflow
+        # according schema properties. This is the meat of the
+        # object-to-api-markup workflow
         #
         # === Example
         #  obj = Invoice.new(:title =>'hello world', :number=>'4711')
-        #  obj_hash = Sk::Api::Schema.to_hash_from_schema(obj, 'v1.0')
         #
-        #  obj_hash => { invoice =>{'title'=>'hello world', 'number'=>'4711' } }
+        #  obj_hash = SK::Api::Schema.to_hash_from_schema(obj, 'v1.0') 
+        #   => { 'invoice' =>{'title'=>'hello world', 'number'=>'4711' } }
+        #
+        #  obj_hash = SK::Api::Schema.to_hash_from_schema(obj, 'v1.0', :fields=>['title'])
+        #   => { 'invoice' =>{'title'=>'hello world' } }
         #
+        #  obj_hash = SK::Api::Schema.to_hash_from_schema(obj, 'v1.0', :class_name=>:document)
+        #   => { 'document' =>{'title'=>'hello world' } }
+        #   
         # === Parameter
         # obj<Object>:: An ruby object which is returned as hash
-        # version<String>:: the schema version, must be a valid folder name see #self.read
+        # version<String>:: the schema version, must be a valid folder name see
+        # #self.read
+        # opts<Hash{Symbol=>Mixed} >:: additional options
+        # 
+        # ==== opts Parameter
+        # class_name<String|Symbol>:: Name of the class to use as hash key. Should be
+        # a lowered, underscored name and it MUST have an existing schema file.
+        # Use it to override the default, which is obj.class.name
+        # fields<Array[String]>:: Fields/properties to return. If not set all
+        # schema's properties are used.
         #
         # === Return
         # <Hash{String=>{String=>Mixed}}>:: The object as hash:
         # { invoice =>{'title'=>'hello world', 'number'=>''4711 } }
-        def to_hash_from_schema(obj, version)
+        def to_hash_from_schema(obj, version, opts={})
+          fields = opts[:fields]
           # get objects class name without inheritance
-          obj_class_name =  obj.class.name.split('::').last.underscore
-          # init data hash
+          real_class_name = obj.class.name.split('::').last.underscore
+          class_name =  opts[:class_name] || real_class_name
           data = {}
           # get schema
-          schema = read(obj_class_name, version)
+          schema = read(class_name, version)
           # iterate over the defined schema fields
           schema['properties'].each do |field, prop|
+            next if fields && !fields.include?(field)
             if prop['type'] == 'array'
               data[field] = [] # always set an empty array
               if rel_objects = obj.send( field )
@@ -100,9 +126,10 @@ module SK
               data[field] = obj.send(field) if obj.respond_to?(field.to_sym)
             end
           end
-          hsh = { obj_class_name => data }
+          hsh = { "#{class_name}" => data }
           #add links if present
-          links = parse_links(obj, schema)
+          real_class_schema = read(real_class_name, version)
+          links = parse_links(obj, real_class_schema)
           links && hsh['links'] = links
           # return hash
           hsh

data/sk_api_schema.gemspec

@@ -5,17 +5,18 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sk_api_schema}
-  s.version = "0.0.18"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Georg Leciejewski"]
-  s.date = %q{2011-03-10}
+  s.date = %q{2011-04-28}
   s.description = %q{SalesKing API JSON schema and utility methods}
   s.email = %q{gl@salesking.eu}
   s.extra_rdoc_files = [
     "README.rdoc"
   ]
   s.files = [
+    "CHANGELOG.rdoc",
     "README.rdoc",
     "Rakefile",
     "VERSION",
@@ -26,6 +27,7 @@ Gem::Specification.new do |s|
     "json/v1.0/comment.json",
     "json/v1.0/company.json",
     "json/v1.0/credit_note.json",
+    "json/v1.0/document.json",
     "json/v1.0/email.json",
     "json/v1.0/email_template.json",
     "json/v1.0/estimate.json",
@@ -39,6 +41,7 @@ Gem::Specification.new do |s|
     "json/v1.0/product.json",
     "json/v1.0/recurring.json",
     "json/v1.0/sub.json",
+    "json/v1.0/tag.json",
     "json/v1.0/text_template.json",
     "json/v1.0/user.json",
     "lib/sk_api_schema.rb",
@@ -48,7 +51,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = %q{http://github.com/salesking/sk_api_schema}
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.5.2}
+  s.rubygems_version = %q{1.6.2}
   s.summary = %q{SalesKing API JSON Schema}
   s.test_files = [
     "spec/sk_api_schema_spec.rb",

data/spec/sk_api_schema_spec.rb

@@ -2,6 +2,9 @@ require 'spec/spec_helper'
 
 describe SK::Api::Schema do
 
+  before :each do
+    SK::Api::Schema.registry_reset
+  end
   it "should read json schema file" do
     schema = SK::Api::Schema.read(:invoice, 'v1.0')
     schema[:title].should == 'invoice'
@@ -87,6 +90,25 @@ describe SK::Api::Schema, 'object parsing' do
                                        "id"=>"some-uuid", "description"=>"Yummi Pork chopped by mexian emigrants", "price_single"=>0.99}}]
   end
 
+  it "should parse object given fields" do
+    @invoice.line_items = [@item]
+    @invoice.client = @client
+    fields = %w(id title client)
+    obj_hash = SK::Api::Schema.to_hash_from_schema(@invoice, 'v1.0', :fields=>fields)
+    obj_hash["invoice"]['client']['client'].should == {"number"=>"911", "addresses"=>[], "id"=>"some-uuid", "organisation"=>"Dirty Food Inc.", "last_name"=>nil}
+    obj_hash["invoice"]["client"]['links'].should_not be_nil
+    obj_hash["invoice"].keys.sort.should == fields.sort
+  end
+
+  it "should use different class name as object hash key" do
+    @invoice.line_items = [@item]
+    @invoice.client = @client
+    obj_hash = SK::Api::Schema.to_hash_from_schema(@invoice, 'v1.0', :class_name=>:document)
+    schema = SK::Api::Schema.read(:document, 'v1.0')
+    # check included fields, which should not be all fields from schema since our dummy invoice object does not responds_to all
+    intersect_keys = schema['properties'].keys & obj_hash["document"].keys
+    intersect_keys.sort.should == obj_hash["document"].keys.sort
+  end
 end
 
 ################################################################################

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sk_api_schema
 version: !ruby/object:Gem::Version 
-  hash: 59
+  hash: 27
   prerelease: 
   segments: 
   - 0
+  - 1
   - 0
-  - 18
-  version: 0.0.18
+  version: 0.1.0
 platform: ruby
 authors: 
 - Georg Leciejewski
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-10 00:00:00 +01:00
+date: 2011-04-28 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -55,6 +55,7 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 files: 
+- CHANGELOG.rdoc
 - README.rdoc
 - Rakefile
 - VERSION
@@ -65,6 +66,7 @@ files:
 - json/v1.0/comment.json
 - json/v1.0/company.json
 - json/v1.0/credit_note.json
+- json/v1.0/document.json
 - json/v1.0/email.json
 - json/v1.0/email_template.json
 - json/v1.0/estimate.json
@@ -78,6 +80,7 @@ files:
 - json/v1.0/product.json
 - json/v1.0/recurring.json
 - json/v1.0/sub.json
+- json/v1.0/tag.json
 - json/v1.0/text_template.json
 - json/v1.0/user.json
 - lib/sk_api_schema.rb
@@ -114,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.2
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: SalesKing API JSON Schema