The web application we are developing allows developers to do an HTTP POST from a form (that they develop) to our servers. We provide them with an API reference for the request and response field names.
One particular requirement of our application is that the response must include all request fields that were originally submitted – kind of like an echo of the request fields in the response.
To try and keep the API intuitive and unambiguous, I have suggested that in the response field names, we prepend those ‘echoed’ request fields with something (e.g. ‘req_’ or ‘request_’) to differentiate them from true response data. However, a few of the guys are not so sure with this approach, and they suggest that we just keep the names the same.
I would appreciate your opinions on this; I’m relatively new to defining APIs so any feedback would be great.
To summarize, the two options on the table are:
Option 1 – Don’t Differentiate Request Fields In Response
request:
name: 'Joe Bloggs'
address: '22 My Street, My City'
amount: '100.00'
response:
transaction_id: '384765'
transaction_time: '2011-12-31T11:59:59Z'
message: 'Your transaction was successful.'
name: 'Joe Bloggs'
address: '22 My Street, My City'
amount: '100.00'
Option 2 – Differentiate Request Fields In Response
request:
name: 'Joe Bloggs'
address: '22 My Street, My City'
amount: '100.00'
response:
transaction_id: '384765'
transaction_time: '2011-12-31T11:59:59Z'
message: 'Your transaction was successful.'
req_name: 'Joe Bloggs'
req_address: '22 My Street, My City'
req_amount: '100.00'
Personally I would not differentiate the request fields as it could get confusing for the developer, it would also require you to have a correct naming convention so that your field names do not clash.