ZSPEC Sample

We will use the example of developing the Trips API for a Travel Bureau product. When writing an effective ZSPEC, it’s crucial to consider the core components that make up any API, including domains, endpoints, methods, parameters, request payload, response, error handling, throttling, and authentication.

Authentication and a few responses are re-used from a common resource to keep this sample short and crisp. We have used almost covered all the elements of ZSPEC in this product to provide you an overview of their functionalities. To learn more, click here and take a look at the dependencies. You can also upload the same zip to ZEST and witness the life cycle of the APIs in a few clicks.

    

        
copy
        

            

        
    
    

         
<resource name="trips" product="travelbureau" pre-loaded="true" specification="1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../xsd/1_0_0/spec.xsd">

    <components>

        <structure name="trips_data" ref-name="trips">
            <property name="trip_name" type="string" required-for="all" nullable-for="none" unique-for="all">
                <description>Name of the trip.</description>
            </property>
            <property name="trip_id" type="long_string" include-for="Request[update], Response[read]" required-for="all" nullable-for="none">
                <description>The unique record ID of the trip.</description>
            </property>
            <property name="destination" type="string" path="destinations:$.destination_name">
                <description>Destination of the trip.</description>
            </property>
            <property name="start_time" type="datetime">
                <description>The starting time of the trip.</description>
            </property>
            <property name="end_time" type="datetime" format="yyyy-MM-dd'T'HH:mm:ss+/-hh:mm" >
                <!-- TO-DO value-condition=">REQUEST:$.body.start_time" -->
                <description>The ending time of the trip.</description>
            </property>
            <property name="no_of_days" type="integer" required-for="all" nullable-for="none">
                <description>The total number of trip days.</description>
            </property>
            <property name="transport_medium" type="string" values="Roadways,Airways,Waterways,Hybrid" extra-value="map-default" default-value="Roadways">
                <description>Your preferred medium of transport.</description>
            </property> 
            <property name="hybrid_details" type="string" condition-for-all="$.body.transport_medium == 'Hybrid'">
                <description>Elaborate your hybrid details and the list of your preferred medium of transport.</description>
            </property>
            <property name="accommodation_type" type="string" values="Hotel,Resort,Vacation Rental,Hostel" invalid-value="map-default" default-value="Hotel">
                <description>Type of your accommodation.</description>
            </property>
            <property name="travelers" type="collections">
                <description>Details of the travelers.</description>
                <structure>
                    <property name="traveler_name" type="collections" path="travelers:$.traveler_name">
                        <description>Name of the traveler.</description>
                    </property>
                    <property name="traveler_email" type="string" nullable-for="all" path="travelers:$.traveler_email">
                        <description>Email ID of the traveler.</description>
                    </property>
                </structure>
            </property>
            <property name="trip_budget" type="integer">
                <description>Budget of your trip.</description>
            </property>
            <property name="adventure_activities" type="object">
                <extend-property type="collections" length="3,-1" condition-for-all="'Automation' :: REQUEST:$.header.service" > 
                    <description>List of adventure activities according to the suggestions of traveler(s).</description>
                    <structure>
                        <property type="string" />
                    </structure>
                </extend-property>
                <extend-property type="boolean" condition-for-all="REQUEST:$.header.service == null || REQUEST:$.header.service != Automation">
                    <description>Denotes whether adventure activities can be included in the trip. 

                        - **true**: Adventure activities will be included in the trip. 
                        - **false**: Adventure activities are not included in the trip. </description>
                </extend-property>
            </property>
        </structure>

        <structure name="wrapper" ref-name="data">
            <property name="trips" type="collections">
                <structure-ref name="trips" />
            </property>
        </structure>

        <content name="resource_data">
            <encode type="application/json" />
            <structure-ref name="data" />
        </content>

        <request-body name="payload">
            <content-ref name="resource_data" />
        </request-body>

        <argument name="ids" location="param" length="10" style="delimiter" delimiter=",">
            <description>Specify the id(s) for which the operation has to take place.</description>
            <content>
                <encode type="application/json" />
                <structure>
                    <property type="collections" path="trips:$.trip_id" />
                </structure>
            </content>
        </argument>

        <argument name="service" location="header" visibility="internal">
            <description>Specify the service from which the resource is consumed.</description>
            <content>
                <encode type="application/json" />
                <structure>
                    <property type="string" values="Automation,Audit,QA" />
                </structure>
            </content>
        </argument>

    </components>

    <info title="Trips API" version="1">
        <description>Trips holds details such as trip itineraries, departure and arrival information, and other relevant data regarding a trip in the Travel Bureau. It offers all four CRUD operations for the effective management of records in the resource.</description>
        <terms-of-service-ref name="destinations.Terms and Conditions" />
        <contact-details-ref name="destinations.Travel Bureau Support" />
        <license-details-ref name="destinations.Apache License 2" />
    </info>

    <resource-config primary-type="simple" primary-structure="trips">
        <path-config data-extraction-path="$.trips">
            <primary path="$.trip_id" />
        </path-config>
    </resource-config>

    <server-ref name="destinations.travel_bureau_server" />

    <url path="/travel_bureau/v1/trips">

        <operation method="get" name="GET trips" category="read">
            <description>This operation fetches the trips details available in the Travel Bureau. You can also provide the IDs of the records to get only the details of particular records.</description>
            <argument-ref name="ids" />
            <argument-ref name="service" />
            <response status="200">
                <description>These are the response JSON keys that represents the trips resource in the Travel Bureau.</description>
                <content-ref name="resource_data" />
            </response>
            <response-ref name="destinations.error_responses" />
            <authentication type="oauth2" name="Authorization" location="header" schema="destinations.iam_oauth2_schema" scopes="TravelBureau.trips.READ"/>
        </operation>

        <operation method="post" name="POST trips" category="create">
            <description>It helps you to add new trips to the Travel Bureau.</description>
            <argument-ref name="service" />
            <request-body-ref name="payload" />
            <response-ref name="destinations.create_success" />
            <response-ref name="destinations.error_responses" />
            <authentication type="oauth2" name="Authorization" location="header" schema="destinations.iam_oauth2_schema" scopes="TravelBureau.trips.CREATE"/>
        </operation>

        <operation method="put" name="PUT trips" category="update">
            <description>It aids you in updating the details of the existing trips data in the Travel Bureau.</description>
            <argument-ref name="service" />
            <request-body-ref name="payload" />
            <response-ref name="destinations.update_success" />
            <response-ref name="destinations.error_responses" />
            <authentication type="oauth2" name="Authorization" location="header" schema="destinations.iam_oauth2_schema" scopes="TravelBureau.trips.UPDATE"/>
        </operation>

        <operation method="delete" name="DELETE trips" category="delete">
            <description>This helps you to delete the existing trips records in the Travel Bureau.</description>
            <argument-ref name="ids" />
            <response-ref name="destinations.delete_success" />
            <response-ref name="destinations.error_responses" />
            <authentication type="oauth2" name="Authorization" location="header" schema="destinations.iam_oauth2_schema" scopes="TravelBureau.trips.DELETE"/>
        </operation>

    </url>

    <authentication type="oauth2" name="Authorization" location="header" schema="destinations.iam_oauth2_schema" scopes="TravelBureau.trips.ALL"/>
    
</resource>