sk_api_schema 0.2.3 → 0.2.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (14) hide show
  1. data/CHANGELOG.rdoc +9 -0
  2. data/README.rdoc +63 -17
  3. data/VERSION +1 -1
  4. data/json/v1.0/address.json +15 -8
  5. data/json/v1.0/client.json +41 -21
  6. data/json/v1.0/credit_note.json +6 -1
  7. data/json/v1.0/document.json +5 -0
  8. data/json/v1.0/estimate.json +7 -2
  9. data/json/v1.0/invoice.json +6 -1
  10. data/json/v1.0/order.json +6 -1
  11. data/json/v1.0/tag.json +8 -0
  12. data/lib/sk_api_schema.rb +1 -1
  13. data/sk_api_schema.gemspec +2 -2
  14. metadata +4 -4
data/CHANGELOG.rdoc CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  A more detailed view of the changes can be found in the {commit messages}[https://github.com/salesking/sk_api_schema/commits/]
4
4
 
5
+ 2011-9
6
+ * search documents by number
7
+ * maxLength information for client and address properties
8
+ * allow tags edit, destroy
9
+
10
+ 2011-7
11
+ * allow new documents with status closed
12
+ * auto-set number+date for new open/closed documents
13
+
5
14
  2011-6
6
15
  * added language field to document, client, email-template
7
16
  * added filter[languages] for documents and clients, to search by one or more languages
data/README.rdoc CHANGED
@@ -4,46 +4,92 @@ Our API definition is using JSON Schema(http://json-schema.org/). A schema
4
4
  describes a resource in terms of available fields, CRUD actions and
5
5
  relationships with other resources.
6
6
 
7
- For ruby users this project provides a gem with some basic utility functions
8
- besides the schema. Other languages should take advantage of the raw json files.
7
+ For ruby pirates this project is available as gem. It provides some utility
8
+ functions to read the schema files and convert objects to their schema notation.
9
+ See {/lib/sk_api_schema.rb}[https://github.com/salesking/sk_api_schema/blob/master/lib/sk_api_schema.rb]
10
+
11
+ Other languages should take advantage of the raw json files.
9
12
 
10
13
  == Tutorial & Docs
11
14
 
12
- * API Browser visualized JSON Schema - http://sk-api-browser.heroku.com/
13
- * API Intro - http://dev.blog.salesking.eu/api/
15
+ * {API Browser visualized JSON Schema}[http://sk-api-browser.heroku.com/]
16
+ * {API Intro}[http://dev.blog.salesking.eu/api/]
17
+ * {Ruby SDK - API Client}[https://github.com/salesking/sk_sdk]
14
18
 
15
19
  == Versioning
16
20
 
17
21
  The main API-version is kept in the folder-name and as long as there are no major
18
22
  changes(breaking backwards compatibility), the version number will remain.
19
23
 
20
- The gem has its own version number. It is used by SalesKing to deliver it's
21
- resources BUT changes might not be directly reflected. To see what version of
22
- the gem we are using go to:
23
-
24
- my.salesking.eu/api/schema?gem_version=1
25
-
26
- A new gem version indicates a change, but we first try it on our staging environment
27
- before any live instances are updated and the schema becomes public available.
28
-
29
- You can get the current schema at your SalesKing api url:
24
+ You can see the current schema at:
30
25
  my.salesking.eu/api/schema
31
26
  my.salesking.eu/api/clients/schema
32
27
 
33
- The schema version(NOT the gem version) can be set with the "v" url parameter
28
+ The schema main version(NOT the gem version) can be set with the "v" url parameter
34
29
  in any call, but is pretty useless as long as we are in v1.0
35
30
  my.salesking.eu/api/clients?v='1.0'
36
31
 
32
+ The gem has its own version number. A new gem version indicates a change, but
33
+ we first try it on our staging environment before any live instances are
34
+ updated and the schema becomes public available. The gem is used by SalesKing
35
+ to deliver it's data BUT changes might not be directly reflected as stated.
36
+ To see the current gem version use:
37
+
38
+ my.salesking.eu/api/schema?gem_version=1
39
+
37
40
  == Save the planet
38
41
 
39
- By default the api returns an object with all available properties(fields). You
40
- can limit those by passing an array or comma-separated string in the fields
42
+ By default the API returns an object with all available properties(fields). You
43
+ can limit those by passing comma-separated string(or array) in the fields
41
44
  parameter:
42
45
  my.salesking.eu/api/clients?fields=id,organisation
46
+
43
47
  my.salesking.eu/api/clients?fields[]=id&fields[]=organisation
44
48
 
45
49
  Please try to only request the fields you really need, to save computing power!
46
50
 
51
+ == Object Structure
52
+
53
+ The primary object types in SK are:
54
+ * Documents
55
+ * Contacts
56
+ * Products
57
+
58
+ Secondary objects cannot exist without a primary(related) object
59
+ * Attachments
60
+ * Comments
61
+ * Messages
62
+ * Tags
63
+
64
+ The third kind are supportive objects
65
+ * Company
66
+ * Users
67
+ * Exports
68
+ * Templates
69
+
70
+ Following list gives you a quick overview of relations with nested urls an how
71
+ parameters work. You can find those in detail when looking at the link section
72
+ of each schema.
73
+
74
+ # GET invoices tagged with hosting and important
75
+ /invoices?filter[tags]=important,hosting
76
+
77
+ # GET orders for given client ids
78
+ /orders?filter[client_ids]=:client_id,:client_id
79
+
80
+ # GET products second page with 100 in list, only id+name
81
+ /products?per_page=100&page=2&fields=id,name
82
+
83
+ # all comments for an invoice
84
+ /invoices/:id/comments
85
+
86
+ # all documents of a client
87
+ /clients/:id/documents
88
+
89
+ # all invoices of a client
90
+ /clients/:id/invoices
91
+
92
+
47
93
  == ToDo:
48
94
 
49
95
  Those relative urls in the link sections, need some love, so please don't rely on
data/VERSION CHANGED
@@ -1 +1 @@
1
- 0.2.3
1
+ 0.2.4
data/json/v1.0/address.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "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.",
4
4
  "properties": {
5
5
  "id": {
6
- "description": "uuid of the adress.",
6
+ "description": "uuid of the address.",
7
7
  "identity":true,
8
8
  "readonly":true,
9
9
  "type":"string"
@@ -11,31 +11,38 @@
11
11
  "city": {
12
12
  "description": "City for the address. Must at least be present for an address.",
13
13
  "required":true,
14
- "type":"string"
14
+ "type":"string",
15
+ "maxLength": 100
15
16
  },
16
17
  "address1": {
17
18
  "description": "Should contain the street or otherwise primary address information.",
18
- "type":"string"
19
+ "type":"string",
20
+ "maxLength": 100
19
21
  },
20
22
  "address2": {
21
23
  "description": "Additional address information, like floor number",
22
- "type":"string"
24
+ "type":"string",
25
+ "maxLength": 100
23
26
  },
24
27
  "pobox": {
25
28
  "description": "Post office box number",
26
- "type":"string"
29
+ "type":"string",
30
+ "maxLength": 10
27
31
  },
28
32
  "zip": {
29
33
  "description": "Zip number of the city. Length must be between 4..10",
30
- "type":"string"
34
+ "type":"string",
35
+ "maxLength": 10
31
36
  },
32
37
  "state": {
33
38
  "description": "Country state of address",
34
- "type":"string"
39
+ "type":"string",
40
+ "maxLength": 100
35
41
  },
36
42
  "country": {
37
43
  "description": "Country of the address.",
38
- "type":"string"
44
+ "type":"string",
45
+ "maxLength": 100
39
46
  },
40
47
  "created_at": {
41
48
  "description": "Date the object was created in SK. Never changes afterwards",
data/json/v1.0/client.json CHANGED
@@ -9,20 +9,24 @@
9
9
  },
10
10
  "number": {
11
11
  "description": "Unique number, auto-created by SK for new client without number.",
12
- "type":"string"
12
+ "type":"string",
13
+ "maxLength": 50
13
14
  },
14
15
  "organisation": {
15
16
  "description": "Name of a company. This or lastname must be present",
16
17
  "required" : true,
17
- "type":"string"
18
+ "type":"string",
19
+ "maxLength": 100
18
20
  },
19
21
  "last_name": {
20
22
  "description": "Last name of a person. At least this or the organisation field must be filled for new records",
21
- "type":"string"
23
+ "type":"string",
24
+ "maxLength": 50
22
25
  },
23
26
  "first_name": {
24
27
  "description": "First name of a person.",
25
- "type":"string"
28
+ "type":"string",
29
+ "maxLength": 50
26
30
  },
27
31
  "gender": {
28
32
  "description": "Can be empty for a company. Is used in salutation",
@@ -31,27 +35,33 @@
31
35
  },
32
36
  "position": {
33
37
  "description": "Position of a person in a company.",
34
- "type":"string"
38
+ "type":"string",
39
+ "maxLength": 50
35
40
  },
36
41
  "title": {
37
42
  "description": "Academical title of a person e.g. Dr., Prof",
38
- "type":"string"
43
+ "type":"string",
44
+ "maxLength": 50
39
45
  },
40
46
  "tax_number": {
41
47
  "description": "Tax number, normally applies to a private person",
42
- "type":"string"
48
+ "type":"string",
49
+ "maxLength": 30
43
50
  },
44
51
  "vat_number": {
45
52
  "description": "VAT number, for a company or person paying value added taxes.",
46
- "type":"string"
53
+ "type":"string",
54
+ "maxLength": 30
47
55
  },
48
56
  "email": {
49
57
  "description": "Email address of the contact.",
50
- "type":"string"
58
+ "type":"string",
59
+ "maxLength": 100
51
60
  },
52
61
  "url": {
53
62
  "description": "An url associated with the person, e.g its company website.",
54
- "type":"string"
63
+ "type":"string",
64
+ "maxLength": 255
55
65
  },
56
66
  "birthday": {
57
67
  "format":"date",
@@ -85,43 +95,53 @@
85
95
  },
86
96
  "bank_name": {
87
97
  "description": "Bank name",
88
- "type":"string"
98
+ "type":"string",
99
+ "maxLength": 70
89
100
  },
90
101
  "bank_number": {
91
102
  "description": "Bank number",
92
- "type":"string"
103
+ "type":"string",
104
+ "maxLength": 35
93
105
  },
94
106
  "bank_account_number": {
95
107
  "description": "Bank account number.",
96
- "type":"string"
108
+ "type":"string",
109
+ "maxLength": 35
97
110
  },
98
111
  "bank_iban": {
99
112
  "description": "IBAN Number of the bank account. Is validated",
100
- "type":"string"
113
+ "type":"string",
114
+ "maxLength": 35
101
115
  },
102
116
  "bank_swift": {
103
117
  "description": "SWIFT BIC- Bank Identifier Code",
104
- "type":"string"
118
+ "type":"string",
119
+ "maxLength": 11
105
120
  },
106
121
  "bank_owner": {
107
122
  "description": "Bank account owner",
108
- "type":"string"
123
+ "type":"string",
124
+ "maxLength": 70
109
125
  },
110
126
  "phone_fax": {
111
127
  "description": "Fax number",
112
- "type":"string"
128
+ "type":"string",
129
+ "maxLength": 30
113
130
  },
114
131
  "phone_office": {
115
132
  "description": "Office phone number",
116
- "type":"string"
133
+ "type":"string",
134
+ "maxLength": 30
117
135
  },
118
136
  "phone_home": {
119
137
  "description": "Private phone number",
120
- "type":"string"
138
+ "type":"string",
139
+ "maxLength": 30
121
140
  },
122
141
  "phone_mobile": {
123
142
  "description": "Mobile phone number",
124
- "type":"string"
143
+ "type":"string",
144
+ "maxLength": 30
125
145
  },
126
146
  "lock_version": {
127
147
  "description": "Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.",
@@ -143,7 +163,7 @@
143
163
  "addresses": {
144
164
  "description": "A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.",
145
165
  "type":"array",
146
- "properties" : {"$ref":"./addresses.json#properties"}
166
+ "properties" : {"$ref":"./address.json#properties"}
147
167
  },
148
168
  "team_id":{
149
169
  "description": "A team uuid. If set only the team and its parent teams can see the record.",
data/json/v1.0/credit_note.json CHANGED
@@ -31,7 +31,7 @@
31
31
  "type":"string"
32
32
  },
33
33
  "status":{
34
- "description": "Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open', following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft invoices can be deleted.",
34
+ "description": "Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.",
35
35
  "default":"draft",
36
36
  "enum":["draft","open","closed"],
37
37
  "type":"string"
@@ -171,6 +171,11 @@
171
171
  "description": "Search in title, number, addressfield",
172
172
  "type":"string"
173
173
  },
174
+ "filter[number]":{
175
+ "title" : "Number",
176
+ "description": "Find by exact number",
177
+ "type":"string"
178
+ },
174
179
  "filter[tags]":{
175
180
  "title" : "Tags",
176
181
  "description": "Filter by a space delimited list of tags",
data/json/v1.0/document.json CHANGED
@@ -125,6 +125,11 @@
125
125
  "description": "Search in title, number, addressfield",
126
126
  "type":"string"
127
127
  },
128
+ "filter[number]":{
129
+ "title" : "Number",
130
+ "description": "Find by exact number",
131
+ "type":"string"
132
+ },
128
133
  "filter[tags]":{
129
134
  "title" : "Tags",
130
135
  "description": "Filter by a space delimited list of tags",
data/json/v1.0/estimate.json CHANGED
@@ -31,9 +31,9 @@
31
31
  "type":"string"
32
32
  },
33
33
  "status":{
34
- "description": "Defaults to draft for new documents, if empty. For new documents with status 'open', the following fields are set if empty: number(next in number schema), date(today), due date(today unless due_days given). Only drafts can be deleted.",
34
+ "description": "Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.",
35
35
  "default":"draft",
36
- "enum":["draft","open","closed"],
36
+ "enum":["draft","open","closed","rejected","billed" ],
37
37
  "type":"string"
38
38
  },
39
39
  "external_ref":{
@@ -156,6 +156,11 @@
156
156
  "description": "Search in title, number, addressfield",
157
157
  "type":"string"
158
158
  },
159
+ "filter[number]":{
160
+ "title" : "Number",
161
+ "description": "Find by exact number",
162
+ "type":"string"
163
+ },
159
164
  "filter[tags]":{
160
165
  "title" : "Tags",
161
166
  "description": "Filter by a space delimited list of tags",
data/json/v1.0/invoice.json CHANGED
@@ -31,7 +31,7 @@
31
31
  "type":"string"
32
32
  },
33
33
  "status":{
34
- "description": "Defaults to draft for new documents, if empty. For new documents with status 'open',the following fields are set if empty: number(next in number schema), date(today), due date(today unless due_days given). Only drafts can be deleted.",
34
+ "description": "Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.",
35
35
  "default":"draft",
36
36
  "enum":["draft","open","closed"],
37
37
  "type":"string"
@@ -171,6 +171,11 @@
171
171
  "description": "Search in title, number, addressfield",
172
172
  "type":"string"
173
173
  },
174
+ "filter[number]":{
175
+ "title" : "Number",
176
+ "description": "Find by exact number",
177
+ "type":"string"
178
+ },
174
179
  "filter[tags]":{
175
180
  "title" : "Tags",
176
181
  "description": "Filter by a space delimited list of tags",
data/json/v1.0/order.json CHANGED
@@ -22,7 +22,7 @@
22
22
  "type":"string"
23
23
  },
24
24
  "status":{
25
- "description": "Defaults to draft for new documents, if empty. For new documents with status 'open', the following fields are set if empty: number(next in number schema), date(today). Only drafts can be deleted.",
25
+ "description": "Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.",
26
26
  "default":"draft",
27
27
  "enum":["draft","open","closed"],
28
28
  "type":"string"
@@ -147,6 +147,11 @@
147
147
  "description": "Search in title, number, addressfield",
148
148
  "type":"string"
149
149
  },
150
+ "filter[number]":{
151
+ "title" : "Number",
152
+ "description": "Find by exact number",
153
+ "type":"string"
154
+ },
150
155
  "filter[tags]":{
151
156
  "title" : "Tags",
152
157
  "description": "Filter by a space delimited list of tags",
data/json/v1.0/tag.json CHANGED
@@ -58,6 +58,14 @@
58
58
  "description": "Sort the results in ASC or DESC"
59
59
  }
60
60
  }
61
+ },
62
+ { "rel": "destroy",
63
+ "href": "tags/{id}",
64
+ "method": "DELETE"
65
+ },
66
+ { "rel": "update",
67
+ "href": "tags/{id}",
68
+ "method": "PUT"
61
69
  }
62
70
  ]
63
71
  }
data/lib/sk_api_schema.rb CHANGED
@@ -96,7 +96,7 @@ module SK
96
96
  #
97
97
  # === Return
98
98
  # <Hash{String=>{String=>Mixed}}>:: The object as hash:
99
- # { invoice =>{'title'=>'hello world', 'number'=>''4711 } }
99
+ # { invoice =>{'title'=>'hello world', 'number'=>'4711' } }
100
100
  def to_hash_from_schema(obj, version, opts={})
101
101
  fields = opts[:fields]
102
102
  # get objects class name without inheritance
data/sk_api_schema.gemspec CHANGED
@@ -5,11 +5,11 @@
5
5
 
6
6
  Gem::Specification.new do |s|
7
7
  s.name = %q{sk_api_schema}
8
- s.version = "0.2.3"
8
+ s.version = "0.2.4"
9
9
 
10
10
  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
11
  s.authors = ["Georg Leciejewski"]
12
- s.date = %q{2011-07-21}
12
+ s.date = %q{2011-10-03}
13
13
  s.description = %q{The SalesKing JSON Schema describes our business API in terms of available objects, their fields and links to url endpoints with related objects. Besides ruby users can use a smal lib with utility methods to load and test the schema files.}
14
14
  s.email = %q{gl@salesking.eu}
15
15
  s.extra_rdoc_files = [
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: sk_api_schema
3
3
  version: !ruby/object:Gem::Version
4
- hash: 17
4
+ hash: 31
5
5
  prerelease:
6
6
  segments:
7
7
  - 0
8
8
  - 2
9
- - 3
10
- version: 0.2.3
9
+ - 4
10
+ version: 0.2.4
11
11
  platform: ruby
12
12
  authors:
13
13
  - Georg Leciejewski
@@ -15,7 +15,7 @@ autorequire:
15
15
  bindir: bin
16
16
  cert_chain: []
17
17
 
18
- date: 2011-07-21 00:00:00 +02:00
18
+ date: 2011-10-03 00:00:00 +02:00
19
19
  default_executable:
20
20
  dependencies:
21
21
  - !ruby/object:Gem::Dependency