Assets - Reading

Get all assets

Syntax

GET /assets.xml

Input

Output

  <assets effective_at="[date]" delta_mode="[new|delta]">
    <asset>  
      <id>[integer]</id>
?     <deleted>true</deleted>
      <fleet_id>[string]</fleet_id>
      <asset_type>[string]</asset_type>
      <effective_at>[date]</effective_at>
      <reported_at>[date]</reported_at>
      [Name/Value Pairs]
    </asset>
    :
    :
    :
  </asset>

Get a particular asset by id

Syntax

GET /assets/[id integer].xml

Input

?fields=[comma-separated desired field names]

Output

  <asset>
    <id>[integer]</id>
?   <deleted>true</deleted>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at> [The latest actual message time]
    <reported_at>[date]</reported_at>   [The time that the message came in]
    [Name/Value Pairs]
  </asset>

Notes

• effective_at is the actual time from the tmu that the message represents.
• effective_at will always be less than the current server time, since future events cannot be considered to have happened yet.
• reported_at is the server time that the message was received

Errors

• If the asset cannot be found

Assets - Writing

Create or update an Asset

Syntax

POST /assets.xml

Input

  <asset>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Output

  <asset>
    <id>[integer]</id>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Notes

• <effective_at>[date]</effective_at> is optional in the input
• effective_at will default to the current time on the server when the request is made if it is not provided
• If the fleet_id is not known, then a new asset is created
• If the fleet_id is known already, then the asset’s details are updated.

Update an Asset by id

Syntax

PUT /assets/[id integer].xml

Input

  <asset>
    <id>[integer]</id>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    [Name/Value Pairs]
  </asset>

Output

  <asset>
    <id>[integer]</id>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Notes

• The input Name/Value pairs MAY include <effective_at>[date]</effective_at>
• effective_at will default to the current time on the server when the request is made
• Use this service to update an asset’s fleet_id or asset_type

Errors

• If a new fleet_id is included, and another asset already has that fleet_id
• If the asset’s id is included and does not match the id in the URL
• If the asset id in the URL is not found

Delete an Asset by id

Syntax

DELETE /assets/[id integer].xml

Input

n/a

Output

  <asset>
    <id>[integer]</id>
    <deleted>true</deleted>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Errors

• If the asset id in the URL is not found

Assets - History

Get a history of all assets

Syntax

GET /assets.xml?start_time=:date&end_time=:date

Input

?fields=[comma-separated desired field names]

Output

  <assets>
    <asset>  
      <id>[integer]</id>
      <fleet_id>[string]</fleet_id>
      <asset_type>[string]</asset_type>
      <effective_at>[date]</effective_at>
      <reported_at>[date]</reported_at>
      [Name/Value Pairs]
    </asset>
    :
  </asset>

Notes

• The output will be for all assets.
• The order will be asset_id, effective_at.
• The effective_at field for the first entry for each asset may be less than start_time

Errors

• If the start_time or end_time cannot be recognised as timestamps
• If the start_time > end_time

Get a history of a particular asset by id

Syntax

GET /assets/[id integer].xml?start_time=:date&end_time=:date

Input

?fields=[comma-separated desired field names]

Output

  <assets>
    <asset>  
      <id>[integer]</id>
      <fleet_id>[string]</fleet_id>
      <asset_type>[string]</asset_type>
      <effective_at>[date]</effective_at>
      <reported_at>[date]</reported_at>
      [Name/Value Pairs]
    </asset>
    :
  </asset>

Notes

• The output will be for a single asset.
• The order will be effective_at.
• The effective_at field for the first entry may be less than start_time

Errors

• If the asset matching the id in the URL cannot be found
• If the start_time or end_time cannot be recognised as timestamps
• If the start_time > end_time