Components

It acts as a cache for other elements that can be reused within a resource and across multiple resources. It reduces the recurrence of similar tags, optimizing the long-winded files with conciser codes. All the child elements of components should have the name attribute with a unique value except for the <structure> in which the ref-name will have the unique value. Whenever you want to reuse a component, enter the unique value in the name attribute of the corresponding ref element.

To reuse the element from another ZSPEC file:

• Both the files should belong to the same version and product. When you refer a component from such a resource, you should prefix the unique name of the component with the resource name.

    

        
copy
        

            

        
    
    

         
<{element-name}-ref name="{resource-name}.{component-name}" />

    

• Here the component-name denotes the name of the child elements of the other resource’s components.

Possible Locations

• Resource

Child Elements

• Example   recurrent
• Structure   recurrent
• Content   recurrent
• Argument   recurrent
• Request Body   recurrent
• Response   recurrent
• Server   recurrent
• Contact Details   recurrent
• License Details   recurrent
• Terms of Service   recurrent
• Tag   recurrent
• Token   recurrent
• Oauth2   recurrent
• Throttling   recurrent

Samples

Within the same components

Assume that there are 2 endpoints for same operations(GET, POST) in the trips resource. This demands you to repeat the resource <structure> multiple times in the ZSPEC file, i.e twice for the GET <response> and twice in the <request-body>. Also, you have to repeat the POST success structure twice.

    

        
copy
        

            

        
    
    

         
sample JSON with primary-structure:
{
	"trips": [
		{
			"trip_name":"Spring Break - John Doe",
			"trip_id": "4437464000001832063",
			"destination": "Bali",
			"start_time": "2023-11-13T17:30:00",
			"end_time": "2023-11-17T22:30:00",
			"no_of_days": 4
		},
		{
			"trip_name":"christmas Break - Diana Williams",
			"trip_id": "4437464000001832227",
			"destination": "London",
			"start_time": "2023-12-20T21:30:00",
			"end_time": "2023-12-28T09:30:00",
			"no_of_days": 7
		}
	]
}

    

    

        
copy
        

            

        
    
    

         
post success: 
{
	"code": "SUCCESS",
	"message": "Record created",
	"status": "success"
}

    

Firstly add the <content> in the components. Then refer it in the <response> and <request-body> again in the components itself.

To reuse the content, use the unique name of the element in the name attribute of content-ref.

    

        
copy
        

            

        
    
    

         
<components>

    <structure ref-name="trips" name="trips_data"> <!-- primary structure of the trips resource -->
        <property name="trip_name" type="string"/>
        <property name="trip_id" type="long_string"/>
        <property name="destination" type="string"/>
        <property name="start_time" type="datetime"/>
        <property name="end_time" type="datetime"/>
        <property name="no_of_days" type="string"/>
    </structure>

    <structure ref-name="data" name="wrapper"> <!-- wrapper of the primary structure -->
        <property name="trips" type="collections">
            <structure-ref name="trips" />
        </property>
    </structure>

    <content name="sample_content">
        <encode type="application/json" />
        <structure>
            <property name="trips" type ="collections">
                <structure-ref name="data" />
            </property>
        </structure>
    </content>

    <response name="get_success" status="200">
        <content-ref name="sample_content" />
    </response>

    <request-body name="req_payload">
        <content-ref name="sample_content" />
    </request-body>

    <response name="post_success" status="201">
        <content>
            <encode type="application/json" />
            <structure>
                <property name="code" type="string" values="SUCCESS"/>
                <property name="message" type="string" values="Record Added"/>
                <property name="status" type="string" values="success"/>
            </structure>
        </content>
    </response>

</components>


    

All these components can be re-used across the same product and version.

Within same ZSPEC file

Now, you have to reuse the <response> and <request-body> from the above components in the two different URLs.

Provide the unique name of these elements in the name attribute of their corresponding ref elements.

    

        
copy
        

            

        
    
    

         
<url path="/travel_bureau/v4/trips">  <!-- First URL -->

    <operation method="get" name="GET trips" category="read">
        <response-ref name="get_success" />
    </operation>

    <operation method="post" name="POST trips" category="create">
        <request-body-ref name="req_payload" />
        <response-ref name="post_success" />
    </operation>

</url>

<url path="/travel_bureau/v4/trips__s"> <!-- Second URL -->

    <operation method="get" name="GET trip" category="read">
        <response-ref name="get_success" />
    </operation>

    <operation method="post" name="POST trip" category="create">
        <request-body-ref name="req_payload" />
        <response-ref name="post_success" />
    </operation>

</url>



    

Reuse from different ZSPEC file

Let us say that we want to reuse the POST operation’s success <response> from the trips resource in the travelers resource. For this requirement, you have to prefix the unique name of the response with its resource name.

Following is how you should use it,

    

        
copy
        

            

        
    
    

         
<url path="/travel_bureau/v4/travelers">
    <operation method="post" name="POST travelers" category="create">
        <request-body name="req_payload">
            <content>
                <encode type="application/json" />
                <structure>
                    <property name="travelers" type ="collections">
                        <structure>
                            <property name="traveler_name" type="string" />
                            <property name="traveler_id" type="long_string"/>
                        </structure>
                    </property>
                </structure>
            </content>
        </request-body>
        <response-ref name="trips.post_success" /> <!-- reusing the success response from the trips resource -->
    </operation>

</url>