Operation

It comprises of the possible operations for a particular URL endpoint in a resource.

Possible Locations

Child Elements

Deprecate
Throttling recurrent
Description
External Document
Tag recurrent
Error
Argument recurrent
Request Body recurrent
Response required recurrent
Authentication recurrent

Info:

The <error> specified at the <content> level always takes precedence because it allows you to set unique conditions for various <response>. On the other hand, the error defined at the operation level is generic for all responses within that particular <operation> and holds the lowest priority.
The <authentication> defined at the operation level holds the higher priority because it allows configuration of different authentication mechanisms for distinct operations. Conversely, the authentication set at the <resource> level is applicable universally to all operations, irrespective of variations in <url>, and is given the lowest priority.

Attributes

Name	Type	Description
method required	String (enum)	The HTTP method that is applicable for a particular operation. The possible values are get, post, put, patch and delete.
name required	String	Name of the operation and it should be unique for a resource.
category required	String (enum)	Defines the category of the operation. The possible values are read, create, update, delete and action.
delay	Long (milliseconds)	The time gap required for the current operator.
validation-delay	Long (milliseconds)	The waiting time for the call back requests in API automation. For instance, consider you want to create a record and get details of the newly created record. Let us say your validation delay is declared as 10s. Once the response for record creation is received, the GET Record call will be fired only after of 10 seconds.
visibility	String (enum)	Decides who can view and use the element. The possible values are internal, private, public. The default value is public.

API Automation

Add auto- as a prefix to these attributes.

Name	Type	Description
sync	Boolean	Denote whether the API calls should be fired sequentially. true: API calls are fired one by one. false (default): API calls are fired concurrently.
callback-get	Boolean	Declare whether the operation should be used for callback verification. true: It will be used for callback verification. false (default): It will not be used for callback verification.
test-dependency	Boolean	State whether the operation should be executed as a dependency. true: It will be used as a dependency. false (default): It will not be used as a dependency.

Info:

At times, the HTTP method may not provide enough information about the operation. For example, action APIs often use the POST method, causing confusion when attempting to create records for automation. To address this, the category attribute assists in identifying the CREATE URL of a resource.

Samples

GET

Assume that in the trips resource, we have the GET operation with the following details,

    
        copy
        
            
        
    
    
         
Authentication type: oAuth2 
Scope: ZohoCRM.settings.trips.READ
- The resource will have an optional parameter called "destination". 
Error condition: The status key in response should carry "error".

    
        copy
        
            
        
    
    
         
Error response

{
    "code": "INVALID_TOKEN",    
    "message": "invalid oauth token",
    "status": "error"
}

The first step to write the primary structure in the <components>.

    
        copy
        
            
        
    
    
         

<operation method="get" name="GET trips" category="read" visibility="internal">
    <description> Here, we have given a sample error condition, authentication, parameter, success response and error response for the trips resource.</description>

    <error condition="$.status == 'error'" />

    <argument name="destination" location="param" required="true">
        <content>
            <encode type="text/plain" />
            <structure name="wrapper">
                <property type="string" path="destinations:$.destination_name"/>
            </structure>
        </content>
    </argument>

    <response name="get_success" status="200">
        <content>
            <encode type="application/json" />
            <structure-ref name="data"/>
        </content>
    </response>

    <response name="invalid_token" status="401">
        <content>
            <encode type="application/json" />
            <structure name="error_body">
                <property name="code" type="string" values="INVALID_TOKEN"/>				
                <property name="message" type="string" values="You have used an invalid oauth token."/>
                <property name="status" type="string" values="error"/>
            </structure>
        </content>
    </response>

    <authentication type="oauth2" name="get" location="header" scopes="TravelAgency.settings.trips.READ" />
</operation>

POST

For the same trips resource as discussed above, we want to define a create operation. Here are the prerequisites of this operation,

    
        copy
        
            
        
    
    
         
- Path of external document: /Users/myfiles/Documents

    
        copy
        
            
        
    
    
         
Success response

{
    "code": "SUCCESS",
    "message": "Trip Created",
    "status": "success"
}

The very first step is to alter the primary structure in the components to suit the <request-body> as the trip_id will not be provided in it.

    
        copy
        
            
        
    
    
         

<components>

    <structure ref-name="trips" name="trips_data"> 
        <property name="trip_name" type="string"/>
        <property name="trip_id" type="long_string" include-for="Request[],Response[read]"/> <!-- this property is excluded in the request body-->
        <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"> 
        <property name="trips" type="collections">
            <structure-ref name="trips" />
        </property>
    </structure>

</components>

Now write the operation for POST as follows,

    
        copy
        
            
        
    
    
         
<operation method="post" name="POST trips" category="create">
    <external-document url="/Users/myfiles/Documents"/>
    <request-body>
        <content>
            <encode type="application/json" />
            <structure ref-name="data">
        </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="Trip Created"/>
                <property name="status" type="string" values="success"/>
            </structure>
        </content>
    </response>
</operation>

UPDATE

Consider that for the same trips resource we need to support the UPDATE operation. The first step is to alter the primary structure in the <components> to suit the <request-body> as the trip_id will be provided in it.

    
        copy
        
            
        
    
    
         
<components>

    <structure ref-name="trips" name="trips_data"> 
		<property name="trip_name" type="string"/>
		<property name="trip_id" type="long_string" include-for="Request[update],Response[read]"/> <!-- this property is included in the update request body-->
		<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"> 
		<property name="trips" type="collections">
			<structure-ref name="trips" />
		</property>
	</structure>

</components>

Following are the additional information that has to be handled in the operation,

    
        copy
        
            
        
    
    
         
User can make 100 calls: in 1 minute
Calls beyond the limit: Operation will be locked for 2 minutes.
- You also want to add this resource to an existing group in the help documentation called "Travel Itinerary".

Write the PUT operation for trips resource as follows,

    
        copy
        
            
        
    
    
         
<operation method="put" name="PUT trips" category="update">
    <throttling threshold="100" duration="60000" lock-period="120000" />
    <tag name="Travel Itinerary" />
    <request-body>
        <content>
            <encode type="application/json" />
            <structure ref-name="data">
        </content>
    </request-body>
    <response name="put_success" status="200">
        <content>
            <encode type="application/json" />
            <structure>
                <property name="code" type="string" values="SUCCESS"/>
                <property name="message" type="string" values="Trip Updated"/>
                <property name="status" type="string" values="success"/>
            </structure>
        </content>
    </response>
</operation>

DELETE

Imagine that, we also need to support the DELETE operation for the trip resource. Following are the few operation specific requirements,
This operation will be deprecated from version 4 and will not be removed in the immediate higher versions.
We also decide to receive the id of the trip that has to be deleted from an <argument>. Now, you should write the DELETE operation with these details as follows,

    
        copy
        
            
        
    
    
         
<operation method="put" name="PUT trips" category="update">
    <argument name="ids" location="param" required="true">
        <content>
            <encode="text/plain" />
            <structure>
                <property type="string" path="trips:$.trip_id" />
            </structure>
        </content>
    </argument>
    <response name="delete_success" status="200">
        <content>
            <encode type="application/json" />
            <structure>
                <property name="code" type="string" values="SUCCESS"/>
                <property name="message" type="string" values="Trip Deleted"/>
                <property name="status" type="string" values="success"/>
            </structure>
        </content>
    </response>
</operation>

Last Updated 2025-05-30 16:54:59 +0530 +0530

Yes

Thank you for your feedback!

Send your feedback to us

Skip

Submit