Naming convention for fields/parameters used in Request and Response Objects

[Greg Madianos]

Wondering about best practices + considerations for naming the fields/parameters within the Request and Response objects for a given call.

Context: developing a RESTful API that involves rental property listings.  A partner service using this API can create a new listing by invoking our CREATE_LISTING call, which has a Request Object with 30+ data fields such as startDate, endDate, propertyAddress, amount, renterName, ownerName, etc.

Many if not all of these fields also appear within the Response Object, e.g. startDate.  Question: for the fields/parameters that *are* contained in *both* objects:

(a) should they have the same name in both Request and Response, or

(b) should we give them slightly different names, e.g. startDate and start_date, with the thought being that it makes it a little easier for a developer to know whether the field/parameter is associated with the Request or with the Response.

Thoughts and/or pointers to existing resources/articles covering this topic appreciated... thanks!

BTW... is the most appropriate term 'fields' or 'parameters' or something else, for referring to the individual data elements that comprise the Request / Response object?  thanks again!

[Petros Ziogas]

My opinion is that you should keep the naming convention the same. 

I don't think the developer should need help in distinguishing the fields. In a way it doesn't matter at all. If an object has a field renderName, thats all the information he needs. It doesn't matter if he provided that data in creation or if it was provided by someone else (through an update). What matters is that this resource has a renderName of X at the given moment.

regarding the fields and parameters question. Parameters is mostly used for parameters of the GET url (e.g. /rentals?startDate=XX) and fields is mostly used for fields of a json object that was submitted to the server.

hope I helped a little.

Petros

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Zacharey Beatty]

I agree with PetrosZ. 

If you keep the request and response names the same, it can allow some code reuse between request and response objects that callers of your API may create.