Hello Karthik,

@api.returns is the decorator, with the help of it you can return anything you want from specific function. So for example generally create method returns the record set of newly created record for particular model. Now for that specific model, if you want to return an dictionary instead of that record set, then you can define @api.returns like as follows,

@api.returns(self, lamda s: {s.id:s}) 
def create(self, vals) 
 res = super(xx, self).create(vals) 
 return res 

Above method will return the dictionary of the record set ( { ID : Recordset } ), not just an record set of specific model.

Another good example to use @api.returns in a best way is :

Generally write method returns the Boolean value ( True or False ). That returned value becomes useless sometimes. So with usage of  @api.returns you can return the Recordset / List of ids which are successfully updated. ( With the magic of inheritance you can perform this thing into your specific model only. It's wonderful, No ?? )

I am not giving more lengthy specifications as other links are good for you to understand this concept into depth. Sometimes just concept clearance with a good example is necessary rather then read the detailed documentations first. And I hope i have been able to clear your confusion regarding @api.returns with proper example.

Hope this helps,