A Quick Summary

Crafting a meticulous and well-structured ZSPEC (ZEST Specification file) is paramount to harnessing the full potential of ZEST. This crucial file serves as the cornerstone for the development, automation, and documentation of RESTful APIs. It enables seamless execution and optimization of API life cycle by providing a comprehensive blueprint.

Let us give you a quick run-through of the most important elements of ZSPEC.

Resource

It is the root element of the ZEST Specification XML file, representing a discrete and identifiable data entity or an object. It encompasses the basic details of the ZSPEC such as name, product, XSD version, and file version. For further details, you can check here.

Components

The components in ZEST context serves as a storage unit, minimizing redundancy by encapsulating reusable elements. Refer to this document to delve deeper into the declaration of elements and their reuse in other places of your ZSPEC and across your product.

Info

It contains the contact details of the support team, license details associated with the resource and the terms and conditions for the user to consume the resource in the most compliant way possible. Check this page to know more about this element.

Resource Config

This element comprises of the basic details of the resource related to primary structure, primary keys and their types. Read more about the resource configuration from here.

Server

The server details like domain, DC, and URL are configured in this element. You can configure different values for a particular part of the URL and also switch the resource to different environments based on your requirements. Refer to this document to learn more about it.

URL

It holds the details about URL endpoint and the possible operations associated with it. You can have multiple URL endpoints for a resource and each endpoint can have multiple operations. Check here for more.

Content

The content decides the MIME type and body details of a response, request and argument. Additionally, you can provide examples of the content which will be rendered as samples in the API help document. Head over here to learn more about this element.

Structure

This element serves as a wrapper for one or more properties in the ZSPEC and stands for a POJO in the source codes. For complex properties like map, collections and array, structure will also function as a child element of a property. Refer to this page to learn more such details about this element.

Property

The property is a functional unit of any argument, response and request-body configured in the ZSPEC. It describes the JSON key-value pairs and even values(collections) alone. See here in detail about it.

Data Path

Data Path is an expression similar to JSON and XML path in ZSPEC, which will be used to fetch data from the data manager. You can also use this expression to fetch data of the current API call using variables. Learn how to construct a data path from here.