Fundamentally, client server communication is really just a conversation between a business and its clients. That is, a human to human interaction.
Understanding this means that we can exploit human’s well developed social communication patterns.
For this entry, we will look into Grice’s Maxims. This are the rules by which ordinary cooperative speech is conducted and as such helping us to structure our own data formats to mimic them.
Let us begin.
Maxim of quantity
Pack as much information as required by the client but not anymore. For example if a request is made for users bio
You need only return the bio information
<person xmlns:atom="http://www.w3.org/2005/Atom"> <atom:link rel="self" href="http://example.org/person/john"/> <id>urn:example:user:1234</id> <name>John</name> <birthday>12/06/78</birthday> <married>true</married> </person>
It would be unnecessary to return the users activity information or even the users address but it would be questionable to not return the user’s name.
Maxim of quality
Do not return what you don’t know to be true or even worse what is outright false. If a request requires information that has since been deleted, do not return the data even if you have it in your archive. Consider instead returning a 404 status code.
This maxim also requires that your application obeys the Rule of least surprise and is not reliable.
Maxim of relation
While before we admonished including too many details, it is important that we include Rel links in our response to ensure that the clients gets the proper context.
In the same vein it is important that we don’t include links that have no context in the current response.
Maxim of manner
You should choose your representation to be as simple as possible for the context in which it is requested. Avoid ambiguity or obscurity of expression by choosing standard data formats that are common practise for similar requests in the industry.
For example use JSON for AJAX requests and HTML for Browser requests. Using YAML for AJAXrequest while valid and simple would be surprising for most clients.
You can read more on Gricean maxim’s from here http://www.sas.upenn.edu/~haroldfs/dravling/grice.html
How do you decide the amount of information to return to your clients? Let’s keep the conversation going.