Zoomed Image
USA
800 691 9120
UK
01225 704844

REST API Overview

xAssets Configuration Guide
REST API

REST API Overview

The xAssets REST API provides programmatic access to your asset management data. External applications, scripts, and automation tools can use the API to query assets, create and update records, execute bulk operations, run transformations, and manage incidents -- all without using the xAssets user interface.

This page introduces the API architecture, authentication model, and common use cases. For step-by-step instructions on making your first API call, see Getting Started.

Prerequisites

  • An xAssets instance accessible over the network (or internet) from the calling application
  • An API Key and Secret, created by your xAssets administrator
  • Familiarity with HTTP requests and JSON or XML data formats

API Interfaces

The API routes all calls through three interfaces, each designed for a different type of operation:

Interface Purpose HTTP Method Use When
CommandProcessor Retrieve data -- queries, asset records, settings, XML POST You need to read data from xAssets
Save Save standard-formatted XML data to database tables POST You need to create or update records
SaveSpecial Execute specialised operations such as disposals, transfers, transformations, and month-end processing POST You need to perform a business operation that goes beyond simple data saving

All three interfaces use the same base URL and authentication mechanism. The command parameter in the request determines which interface is invoked.

Connection Types

Type Description Recommended
RESTful HTTP-based REST API using bearer tokens Yes -- standard API use for most integrations
WebSocket Persistent WebSocket connection (WSS) Yes -- real-time or persistent connections
SOAP Legacy SOAP/XML web service No -- available for backward compatibility only

RESTful is recommended for most integrations. WebSocket connections are useful for applications that maintain a constant connection or require real-time updates.

Authentication

All API calls require authentication. The workflow is:

  1. Obtain credentials -- get an API Key and Secret from your xAssets administrator (see Getting Started for how to create one)
  2. Authenticate -- send a POST request with your API Key and Secret to obtain a bearer token
  3. Make requests -- include the bearer token in the Authorization header of all subsequent requests

The bearer token is valid for the session duration. If it expires, call the logon endpoint again to obtain a new token.

Base URL

All API endpoints use the base URL of your xAssets installation:

https://your-server/a.aspx

The command parameter in each request determines which operation is performed.

Common Operations

Task Interface API Method
Query asset data CommandProcessor AssetXML
Retrieve query results CommandProcessor RunQuery
Save asset changes Save WebSaveXML
Run a transformation SaveSpecial SpecialDBTransformRun
Run month-end depreciation SaveSpecial SpecialAccountingProcess
Dispose or transfer assets SaveSpecial SpecialBulkDisposal
Get settings CommandProcessor GetSpecialOption

Using Transformations Instead of Direct API Calls

Many tasks can be achieved using AMSX transformations rather than direct API programming. Consider using transformations when:

  • The operation can run on a schedule, trigger, or from a menu item
  • No external programming environment is available
  • The operation involves data import, export, notifications, report emailing, or cloud integration
  • You want the logic to be maintained within xAssets rather than in an external system

Transformations are written in the AMSX scripting language (see The AMSX Programming Language). Use the REST API when you need real-time request/response interaction from an external application, or when the calling system needs to inspect the response before deciding what to do next.

API Reference

For the full API reference including all endpoints, parameters, and working code examples, see the API Programmer's Guide.