Data API

The ZEST Data API is the primary way apps & integrations interact with a ZEST website. It allows you to pull & push data directly from most ZEST data sources. Features of the API include:

  • A REST API, that communicates over HTTPS.
  • This is a versioned API. The latest version is v3.
  • The API sends and receives XML.
  • Unfortunately JSON is not supported - it came on the scene a bit late after the API had been live in production for some time, and we have not upgraded it to add support for it. However there are many good libraries for working with & manipulating XML.
  • Apps & integrations must authenticate to interact with the Data API.
  • A code of conduct applies to using the API - including rate limiting your requests to avoid placing excessive load on our servers & negatively affecting load times on your connected website.

Getting started

Make sure you read our getting started documentation to learn how to gain access to our APIs, and authenticate a request.

Working with the ZEST Data API

Like most REST API's, you can create, read, update & delete various resources using the different HTTP methods:

  • GET - retrieve a record (or collection of records)
  • POST - create a new record (or update a matching existing record)
  • PUT - update an existing record and throw an error if it doesn't exist
  • DELETE - delete a record

This API offers resources for most data models within the ZEST system, so a lot of low level capability is exposed. However it is low level - meaning in some cases you need to work with the raw data structures & formats that ZEST accepts - which are not always optimised for easy CRUD operations.

Note: If your HTTP client cannot handle a specific HTTP method, you can pass it in as the querystring parameter eg. _method=PUT.

Resoures

The Data API provides deep access to the data powering any website - exposing the majority of its data models. A lot of them are very low level - essentially exposing raw database tables as XML Resources and allowing you CRUD operations on them. Some of the more commonly accessed resources have an interface layer providing them with a cleaner developer experience.

Some of the more commonly used resources include:

Learn more about the resources exposed by the Data API.

Extending REST - efficiently joining resources

One of the big downsides of REST is it can be somewhat inefficient, requiring multiple API requests to retrieve data from multiple related resource in order to get a full picture of e.g. a product or an order. In a lot of modern APIs, GraphQL is used to tackle this problem. However our Data API was generated long before GraphQL came onto the scene - so we had to come up with a solution of our own.

The Data API allows you to join resources into a single request by defining a "resource specification" - which operates much like you might do an SQL outer join. For example you can retrieve the resource for Order ORD00512 with all of its associated Orderline resources by submitting the following GET request:

GET https://www.clientwebsite.nz/API/V3/Order+Orderline/ORD00512

The resource specification approach allows a lot of flexibility in structuring your requests, even allowing unlimited-depth nested joining (e.g. you could extend the resource specification to retrieve Product resources related to each Orderline in the request above).

Read the full documentation on resource specifications for a full reference on this area.

API Discoverability

The API is designed to be (to some extent) "self documenting" - providing endpoints to list all supported resources, and outputting metadata and documentation about available resources and resource capability as HTML, XML or XSD schemas.

Learn more in the discoverability documentation.

FAQ

I just want to upload/download spreadsheets?

Yes you can. ZEST provide the ability to import or export many resources to/from spreadsheets.

Have a look at the using spreadsheets documentation for more information.

Are the plans to offer JSON?

Not at this stage. XML can be a bit of a pain in some scenarios, but not suffienctly so to motivate us to rework various concepts in the APIs to support JSON.

Do you have a GraphQL API?

Not at this stage - but our extended REST implementation does provide some of the benefits of GraphQL when retrieviong data. Check out our resource specifications implementation for further details.

I can't get XYZ resource to do what I want - can you help?

Sure - we offer both free and paid support. Check out the developer support documentation for more information.

I don't want to build this integration myself, can Zeald just do it for me?

Sure - we regularly integrate software with ZEST websites according to a customers specific requirements. Get in touch with sales@zeald.com to discuss what assistance you would like.