README.md in jess-0.1.0 vs README.md in jess-0.2.0

- old
+ new

@@ -89,13 +89,30 @@ ```ruby computer.extension_attributes._json # => [{ ... }] ``` +## Gotchas + +Beware of these gotchas due to limitations of the JSS JSON API. + +### Timestamps + Jess does not perform any type conversions. For example, timestamps are provided exactly as returned in the original JSON; they are not converted to Ruby DateTime objects. ```ruby -computer.purchasing.po_date_utc # => "2016-03-18T00:00:00.000-0500" +computer.purchasing.po_date_utc # => "2016-03-18T00:00:00.000-0500" +computer.purchasing.po_date_epoch # => 1399698000000 +``` + +### Unspecified values + +JSS does a poor job of indicating unspecified values. For example, a computer where the bus speed cannot be determined will return `0` rather that `null` for the `bus_speed` JSON value. Likewise, unspecified string values are `""`, and unspecified timestamps are `""` or `0` instead of `null`. Jess passes these values straight through without any interpretation, so be aware that just because an attribute is *truthy* does not mean it has a useful value. + +```ruby +# A computer without warranty information +computer.purchasing.warranty_expires # => "" +computer.purchasing.warranty_expires_epoch # => 0 ``` ## Why not ruby-jss? The [ruby-jss](http://pixaranimationstudios.github.io/ruby-jss/) gem is the most popular Ruby library for accessing the JSS API. Compared to Jess, ruby-jss has many more features, and is probably the more suitable solution for most use cases. So when might you use Jess instead?