URL

This element contains the endpoint details along with the possible operations for the URL.

Possible Locations

• Resource

Child Elements

• Operation   required recurrent

Attributes

Name	Type	Description
path required	String	Endpoint of the URL.

Configuring Variable Paths

The variable paths in a URL often changes. For example, in the URL /api/v1/users/900000000123, the ID changes frequently, so this part is a variable in the URL path.

To configure such path variables, use:

    

        
copy
        

            

        
    
    

         
<url path="/api/v1/users/{userId}">
</url>

    

Here, we define the variable name within single curly braces.

In every operation below this URL tag, we need to define an argument for the path variable using the name we specified:

    

        
copy
        

            

        
    
    

         
<url path="/api/v1/users/{userId}">
    <operation name="Get User">
        <argument name="userId" location="variable" ...>
            .....
        </argument>
        ......
    </operation>

    <operation name="Update User" ....>
        <argument name="userId" location="variable" ...>
            .....
        </argument>
        ......
    </operation>
</url>

    

This example defines a path variable (userId) and ensures that each operation under the URL specifies this variable as an argument.

Sample

Single operation

Assume that you are writing the url for GET operation of trips resource with the following information.

    

        
copy
        

            

        
    
    

         
success response:
{
	"trips": [
		{
			"trip_name":"Spring Break - John Doe",
			"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",
			"destination": "London",
			"start_time": "2023-12-20T21:30:00",
			"end_time": "2023-12-28T09:30:00",
			"no_of_days": 7
		}
	]
}

    

    

        
copy
        

            

        
    
    

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

    

You have to declare the primary structure of the trips resource in the <components> before defining the url.

    

        
copy
        

            

        
    
    

         

<!-- primary structure of trips resource -->
<structure ref-name="trips" name="trips_data">
	<property name="trip_name" type="string"/>
	<property name="trip_id" type="long_string"/> <!-- Corrected this tag -->
	<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>

<!-- wrapper of the primary structure -->

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



    

Now, declare the url as follows:

    

        
copy
        

            

        
    
    

         
<url path="/travel_bureau/v4/trips">
	<operation method="get" name="GET trips" category="read">
		<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>
					<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>
	</operation>
</url>


    

---

Multiple operations

Consider that we aim to modify the URL for both the POST and GET operations of the trips resource. In this scenario, the GET response will serve as the request body for the POST, excluding the trip_id <property>. To achieve this, you need to adjust the primary structure and add common error <response> to the <components> of this resource to accommodate both operations. Below is the modified components of trips resource,

    

        
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]"> <!-- include-for attribute is used to neglect the property in CREATE operation -->
		<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>
	<response name="invalid_token" status="401">
		<content>
			<encode type="application/json" />
			<structure>
				<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>
</components>

    

Define the url for two different operations in the following way,

    

        
copy
        

            

        
    
    

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

	<operation method="get" name="GET trips" category="read">
		<response name="get_success" status="200">
			<content>
				<encode type="application/json" />
				<structure-ref name="data" />
			</content>
		</response>
		<response-ref name="invalid_token" />
	</operation>

	<operation method="post" name="POST trips" category="create">
		<request-body name="request">
			<content>
				<encode type="application/json" />
				<structure-ref name="data" />
			</content>
		</request-body>
		<response name="post_success" status="201">
			<content>
				<encode type="application/json" />
				<structure name="body">
					<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>
		<response-ref name="invalid_token" />
	</operation>
</url>