Choosing an API

Agility exposes several API surfaces. They overlap, and how you query — tight projections, real filters, explicit paging — matters more than which one you pick. But each surface has capabilities the others lack, and starting on the right one saves rework later. This page is the decision point: read it before you write any code.

Typically start with api/asset and meta.v1:

• api/asset is the one-stop shop: its query command carries the same document structure as query.v1, and the same surface creates, updates and invokes operations — one asset at a time or in batches.
• meta.v1 tells you what the schema looks like before you touch it.

Reach for the other surfaces when they offer something api/asset does not.

If you want to…	Use
Query, create, update and run operations — most data work	api/asset
Discover asset types, attributes, relations, operations	meta.v1
Read history, read as of a past moment, or get a defaulted template for a new asset	rest-1.v1
Read with a leaner response shape	query.v1
Localize labels and terminology	loc-2.v1
React to changes instead of polling	Webhooks

Decision Table

Dimension	api/asset	meta.v1	rest-1.v1	query.v1
Primary purpose	One-stop shop: query, create, update, run operations	Describe the schema	Read/write individual assets, history, templates	Read assets
Direction	Read and write	Read only	Read and write	Read only
Payload style	YAML or JSON commands (query/create/update/execute)	JSON/XML schema documents	URL-addressed asset + JSON or XML body	JSON query document (from/select/where/…)
Filtering power	The same query document as query.v1, embedded as its query command	N/A	Full filter grammar via where/filter; flat attribute-path selection via sel	where, filter, sort, page, asof, plus nested relation projection
Writes per request	Many assets	None	One asset	None
Relations	Traverse and project in queries; set in writes	Describes relations, doesn't return data	One hop at a time	Traverse and project nested relations
Historical data	Yes (asof in the query command)	No	Yes (the /rest-1.v1/Hist namespace, asof)	Yes (asof, moments)
Typical latency	One round trip per batch	Cacheable, changes rarely	One round trip per asset	One round trip for a whole graph
Best for	Most integrations: imports, migrations, read-modify-write, mass changes	Dynamic forms, validation, code generation	History audits, new-asset templates, XML clients	Lean read-only feeds and dashboards
Avoid when	You need a defaulted new-asset template	You need actual asset data	You are touching hundreds of assets in a loop	You need to write, or need response metadata such as total counts

How to Choose, in Order

1. Start with api/asset. Its query command gives you the full query document — filtering, sorting, paging, relation projection — and the same surface creates, updates and runs operations, singly or in batches. It is the only surface that mixes reads, writes and operations in one request.
2. Pair it with meta.v1. Learn the schema first, cache the result, and validate against it. Attribute names differ between instances because of custom fields.
3. Reach for rest-1.v1 when you need what api/asset does not offer: the /rest-1.v1/Hist namespace to enumerate an asset's full change history, /rest-1.v1/New for a defaulted new-asset template, or an XML payload. (Point-in-time reads need no switch — asof works in api/asset and query.v1 too.)
4. Use query.v1 when a leaner response is worth it. It shares its query semantics with api/asset's query command and returns a smaller response structure — but that response omits metadata such as total counts, which matters as soon as you page through a large result set.
5. Do you need to know when something changed? Prefer webhooks over polling on a timer.

The same decision as a picture:

tip

Most integrations need only two surfaces: meta.v1 once at startup to learn the schema, and api/asset for everything else. Adding rest-1.v1 for history or templates, or query.v1 for lean read feeds, is normal — but they are additions, not the starting point.

warning

Do not use rest-1.v1 in a loop as a substitute for api/asset. It multiplies round trips, and every request carries the full authentication and processing overhead.

Note that api/asset is not one atomic transaction — it deliberately breaks the work into several, which is what stops a large import from blocking other users. See Performance.

Related Topics

• Quickstart — make your first authenticated call
• Authentication — access tokens, Basic authentication and headers
• Assets and Attributes — the data model
• Payload patterns — request shapes that work well