sk_api_schema 0.3.4 → 0.4.0

data/CHANGELOG.rdoc

@@ -3,6 +3,7 @@
 A more detailed view of the changes can be found in the {commit messages}[https://github.com/salesking/sk_api_schema/commits/]
 
 2012-06
+* add payments link to invoice, credit_note
 * add due_date and due_days to order
 * Deprecate payment.method in favour of payment.payment_method bcs 'method' is a keyword in programming
 * test with travis-ci.org

data/README.rdoc

@@ -1,14 +1,15 @@
 = SalesKing API Schema
 
-Our API is described with JSON Schema's (http://json-schema.org), describing our objects(resources) in a readable JSON format:
+{<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]
+
+Our API (objects,resources) is described with JSON Schema (http://json-schema.org).
+Each Object has its own description, with those top-level keys:
 
   {
-    "title": "client",
-    "properties": { ...},
-    "links": [ .. ]
+    "title": "client",      // object type
+    "properties": { .. },   // field descriptions
+    "links": [ .. ]         // CRUD actions, relationships to other resources
   }
-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
 
@@ -24,38 +25,6 @@ Other languages should take advantage of the raw json files.
 * {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:
@@ -99,15 +68,86 @@ of each schema.
     # all invoices of a client
     /clients/:id/invoices
 
+== Field types & formats
+
+Most of the fields are of type 'string'. Their format(espacially date fields)
+is casted on our side. We try to go with the {formats}[http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.23] and {types}[http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.1] defined by JSON-Schema
+
+All text MUST be UTF-8 encoded.
+
+Some example fields:
+
+    "title":{
+     "description": " Cut-off after 255 Characters",
+     "type":"string",
+     "maxLength": 255
+    },
+    "notes_before":{
+     "description": "Long Text is a custom format: see notes below",
+     "type":"string"
+     "format":"text"
+    },
+    "net_total":{
+      "description": "Number with 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "status":{
+      "description": "Allowed values are in enum list",
+      "default":"draft",
+      "enum":["draft","open","closed","rejected","billed" ],
+      "type":"string"
+    },
+    "created_at":{
+      "description": "Date time ISO 8601 format: YYYY-MM-DDThh:mm:ssZ",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+
+*Text-Format* length varies, between ~16,000 to 65.535, with the occurence of non-ASCII Characters {see this post on stackoverflow}[http://stackoverflow.com/questions/4420164/how-much-utf-8-text-fits-in-a-mysql-text-field]
+
+== 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!
+
+
 == 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:
+Tested with {travis-ci}[http://travis-ci.org/salesking/sk_api_schema], but of
+course you can run them too. Install required gems with bundler and go for it:
   # git clone
   # cd into sk_api_schema dir
   bundle install

data/json/v1.0/address.json

@@ -1,79 +1,81 @@
 { "type":"object",
   "title": "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": {
-      "description": "uuid of the address.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
       "identity":true,
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     },
-    "city": {
+    "city":{
       "description": "City for the address. Must at least be present for an address.",
       "required":true,
       "type":"string",
       "maxLength": 100
     },
-    "address1": {
+    "address1":{
       "description": "Should contain the street or otherwise primary address information.",
       "type":"string",
       "maxLength": 100
     },
-    "address2": {
+    "address2":{
       "description": "Additional address information, like floor number",
       "type":"string",
       "maxLength": 100
     },
-    "pobox": {
+    "pobox":{
       "description": "Post office box number",
       "type":"string",
       "maxLength": 10
     },
-    "zip": {
+    "zip":{
       "description": "Zip number of the city. Length must be between 4..10",
       "type":"string",
       "maxLength": 10
     },
-    "state": {
+    "state":{
       "description": "Country state of address",
       "type":"string",
       "maxLength": 100
     },
-    "country": {
+    "country":{
       "description": "Country of the address.",
       "type":"string",
       "maxLength": 100
     },
-    "created_at": {
+    "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards",
       "format":"date-time",
       "readonly":true,
       "type":"string"
     },
-    "updated_at": {
+    "updated_at":{
       "description": "Date the object was edited in SK.",
       "format":"date-time",
       "readonly":true,
       "type":"string"
     },
-    "address_type": {
+    "address_type":{
       "description": "Type of the address, as seen by vCard definition. There can only be one type. Inside of SK you can use placeholders like client.parcel_address.city to access the first parcel adr(Same for work_ / home_). <br/>Besides the placeholder default_address, always returns the first address found. Sorting is done by the order(if set) else by date, newest first.",
       "enum":["work","home", "parcel"],
       "type":"string"
     },
-    "order": {
+    "order":{
       "description": "Addresses are normally sorted by date, newest first. If you need to strongly rely on their sorting e.g. default_address (always first) or have multiple addresses of one type(3 parcel), use this field for all adrs. <br/>Single adrs are used in placeholders like: addresses.2.city, returning the second adr found(not necessarily one with order=2).",
       "type":"integer"
     },
-    "lat": {
-      "description": "Geolocation latitude",
-      "type":"string"
+    "lat":{
+      "description": "Geo-Location latitude",
+      "type":"number"
     },
-    "long": {
-      "description": "Geolocation longitude",
-      "type":"string"
+    "long":{
+      "description": "Geo-Location longitude",
+      "type":"number"
     },
-    "_destroy": {
+    "_destroy":{
       "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

@@ -1,53 +1,60 @@
 { "type":"object",
   "title": "attachment",
   "description":"An file attachment",
-  "properties": {
-    "id": {
+  "properties":{
+    "id":{
       "description": "uuid of the object.",
       "identity":true,
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     },
-    "filename": {
+    "filename":{
       "description": "The filename as set when uploaded",
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 255
     },
-    "disk_filename": {
+    "disk_filename":{
       "description": "Unique filename set by SK",
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 255
     },
-    "url": {
+    "url":{
       "description": "File download url. Unique and valid for 15 minutes, public accessible.",
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "format": "uri"
     },
-    "related_object_type": {
+    "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": {
+    "related_object_id":{
       "description": "uuid of the attachment parent object.",
       "required":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     },
-    "content_type": {
+    "content_type":{
       "description": "Auto detected on upload. Might not always reflect the real content type",
       "readonly":true,
       "type":"string"
     },
-    "size": {
+    "size":{
       "description": "Filesize in kb. Auto detected on upload.",
       "readonly":true,
       "type":"integer"
     },
-    "is_signed": {
+    "is_signed":{
       "description": "True if the file(pdf) has been digitally signed.",
       "type":"boolean"
     },
-    "created_at": {
+    "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards",
       "format":"date-time",
       "readonly":true,
@@ -55,7 +62,9 @@
     },
     "team_id":{
       "description": "A team uuid. If set only the team and its parent teams can see the record.",
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     }
 
   },

data/json/v1.0/auth_permission.json

@@ -1,29 +1,36 @@
 {"type":"object",
   "title": "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": {
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
       "identity":true,
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     },
-    "full_name": {
+    "full_name":{
       "description": "Context_name and name localized: API Clients read - API Kunden anzeigen",
-      "type":"string"
+      "type":"string",
+      "maxLength": 255
     },
-    "name": {
+    "name":{
       "description": "Name for the permission. Since a permission groups multiple privileges the name reflects what someone is allowed to do: read, update, delete. With 'read' granting acccess to the 'index' and 'show' actions of a resource.",
-      "type":"string"
+      "type":"string",
+      "maxLength": 255
     },
     "context_name":{
-      "description": "The context for the permission, beeing a resource: clients, emails",
+      "description": "The context for the permission, being a resource: clients, emails",
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 255
     },
-    "privilege_list": {
+    "privilege_list":{
       "description": "A permission has many privileges which define the actions someone can execute. Such actions are resource methods like index, update, edit, show",
       "type":"string",
-      "readonly":true
+      "readonly":true,
+      "maxLength": 255
     }
   },
 

data/json/v1.0/client.json

@@ -1,88 +1,91 @@
 {"type":"object",
   "title": "client",
   "description": "A client as seen by SalesKing",
-  "properties": {
-    "id": {
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
       "identity":true,
       "readonly":true,
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     },
-    "number": {
+    "number":{
       "description": "Unique number, auto-created by SK for new client without number.",
       "type":"string",
       "maxLength": 50
     },
-    "organisation": {
+    "organisation":{
       "description": "Name of a company. This or lastname must be present",
       "required" : true,
       "type":"string",
       "maxLength": 100
     },
-    "last_name": {
+    "last_name":{
       "description": "Last name of a person. At least this or the organisation field must be filled for new records",
       "type":"string",
       "maxLength": 50
     },
-    "first_name": {
+    "first_name":{
       "description": "First name of a person.",
       "type":"string",
       "maxLength": 50
     },
-    "gender": {
+    "gender":{
       "description": "Can be empty for a company. Is used in salutation",
       "enum":["male", "female"],
       "type":"string"
     },
-    "notes": {
+    "notes":{
       "description": "Notes for a contact. For day to day information you should use comments instead.",
       "type":"string",
-      "maxLength": 65000
+      "format": "text"
     },
-    "position": {
+    "position":{
       "description": "Position of a person in a company.",
       "type":"string",
       "maxLength": 50
     },
-    "title": {
+    "title":{
       "description": "Academical title of a person e.g. Dr., Prof",
       "type":"string",
       "maxLength": 50
     },
-    "tax_number": {
+    "tax_number":{
       "description": "Tax number, normally applies to a private person",
       "type":"string",
       "maxLength": 30
     },
-    "vat_number": {
+    "vat_number":{
       "description": "VAT number, for a company or person paying value added taxes.",
       "type":"string",
       "maxLength": 30
     },
-    "email": {
+    "email":{
       "description": "Email address of the contact.",
       "type":"string",
       "maxLength": 100
     },
-    "url": {
+    "url":{
       "description": "An url associated with the person, e.g its company website.",
       "type":"string",
       "maxLength": 255
     },
-    "birthday": {
+    "birthday":{
       "format":"date",
       "type":"string"
     },
-    "tag_list": {
-      "description": "Space separated list of tags.",
+    "tag_list":{
+      "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
       "type":"string"
     },
-    "created_at": {
+    "created_at":{
       "description": "Date the record was created in SK. Never changes afterwards.",
       "format":"date-time",
       "readonly":true,
       "type":"string"
     },
-    "updated_at": {
+    "updated_at":{
       "description": "Last date when the record was edited.",
       "format":"date-time",
       "readonly":true,
@@ -98,81 +101,83 @@
       "enum":["cash","bank_transfer","credit_card","paypal","direct_debit","cheque", "moneybookers", "premium_sms"],
       "type":"string"
     },
-    "bank_name": {
+    "bank_name":{
       "description": "Bank name",
       "type":"string",
       "maxLength": 70
     },
-    "bank_number": {
+    "bank_number":{
       "description": "Bank number",
       "type":"string",
       "maxLength": 35
     },
-    "bank_account_number": {
+    "bank_account_number":{
       "description": "Bank account number.",
       "type":"string",
       "maxLength": 35
     },
-    "bank_iban": {
+    "bank_iban":{
       "description": "IBAN Number of the bank account. Is validated",
       "type":"string",
       "maxLength": 35
     },
-    "bank_swift": {
+    "bank_swift":{
       "description": "SWIFT BIC-  Bank Identifier Code",
       "type":"string",
       "maxLength": 11
     },
-    "bank_owner": {
+    "bank_owner":{
       "description": "Bank account owner",
       "type":"string",
       "maxLength": 70
     },
-    "phone_fax": {
+    "phone_fax":{
       "description": "Fax number",
       "type":"string",
       "maxLength": 30
     },
-    "phone_office": {
+    "phone_office":{
       "description": "Office phone number",
       "type":"string",
       "maxLength": 30
     },
-    "phone_home": {
+    "phone_home":{
       "description": "Private phone number",
       "type":"string",
       "maxLength": 30
     },
-    "phone_mobile": {
+    "phone_mobile":{
       "description": "Mobile phone number",
       "type":"string",
       "maxLength": 30
     },
-    "lock_version": {
+    "lock_version":{
       "description": "Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.",
       "type":"integer"
     },
-    "cash_discount": {
+    "cash_discount":{
       "description": "Default cash discount for new invoices.",
       "type":"number"
     },
-    "due_days": {
+    "due_days":{
       "description": "Default due days for new invoices.",
       "type":"integer"
     },
-    "address_field": {
+    "address_field":{
       "description": "Returns the address field used on new docs. Consist of Organisation name and default(first) address",
       "readonly":true,
       "type":"string"
     },
-    "addresses": {
+    "addresses":{
       "description": "A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.",
       "type":"array",
       "properties" : {"$ref":"./address.json#properties"}
     },
     "team_id":{
       "description": "A team uuid. If set only the team and its parent teams can see the record.",
-      "type":"string"
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     }
   },
   "links":[