Functions - get message
From The Socknet
get_message is used to get the body and related data of a message in the Socknet. Generally the requesting entity has learned of this message via notify_message.
Contents |
Specification
POST get_message
{ from: { openid: "http://the-user.com/" },
guid: {
openid: "http://friend.com/",
id: "35"
}
}
->
{ message: "I just got a root canal!",
replies_accepted: true,
created: "Tue, 10 Aug 2010 02:56:43 GMT",
edited: "Tue, 10 Aug 2010 02:56:43 GMT"
}
get_message must be called via POST.
The request must include a guid field which describes the message's GUID. The openid or serviceid of this field must be the OpenID or Service ID of the recipient. Otherwise the recipient should return an error.
The request may include a revisions field holding either the string "all" or an array of HTTP dates.
The response must include a message field holding a string in Socknet Message Format.
The response must include a replies_accepted field holding a boolean value indicating whether the message owner will display and/or forward messages from the requesting user. For this purpose it is a good idea to include the from field in the request.
The response must include a created field which holds a date in HTTP format.
The response must include a edited field which holds a date in HTTP format.
The response may include a recipients field which holds an array of objects representing services or users. This field indicates the entities for whom the message is "intended". It does not indicate that no one else should receive the message. For that see the next field, private.
The response may include a private field which holds a boolean. This field indicates that the message should not be forwarded to anyone except the entities in the recipients field. recipients is required if private is present.
The response may include an edits field which holds an array of date strings.
The response may include a deleted field which holds a boolean. If this field is true, no message field is necessary.
The response may include a tag field which holds an array of strings identifying keywords related to the message.
If the request included a revisions field, then the response may include a revisions field holding an object whose keys are the dates submitted and whose values are message objects representing the state of the message at each date. If the revisions field contained the string "all", then the keys are generated from the actual revision dates of the message edits.
Support
Providers must support this function.
Services must support this function.
Further Reading
Revisions
Support for revisions is optional, and the accuracy or existence of the results is not assured. In addition, providers are encouraged to restrict the number of revisions returned to a reasonable length.
Note that the dates in the revision request field need not be the actual dates of any message revision. The results will show the revisions that EXISTED at each of those dates. Providers MAY choose to only show any revision once, although this complicates a requester's task to determine which request dates fit with which result. In cases like this, many requesters will simply ignore the missing data.
A deleted message may still be accessible via revisions. Or not.
Example usage
Message B is a reply to Message A. Message B was created yesterday, and Message A was created the day before but then edited today. It is unclear whether the new version of Message A makes sense with Message B, so the reader may want to know what Message A looked like when Message B was written.
