User:Infinity Linden/OGP Serialization And Transport
BTW... this is a recommendation only. it's not canonical. it's here just so people can comment on it.
once everyone comments on it and we get agreement, i'll put something in the official spec and a note here saying it's more canonical than it is now.
did i mention this is not canonical?
Supported Media Types
Many OGP Protocol messages are communicated as RESTful requests to services accessed via HTTP. There are three well-documented formats these messages may be in, and a MIME Media Type for each:
All OGP requests and responses MUST be one of these three types. In the past media types such as 'application/xml' and 'application/json' have been used. Moving forward, these media types should be considered deprecated.
The Requester of a protocol interaction uses the Content-Type: header to identify the media type of the request data content. It may use the Accept: header to indicate a preference for the media type of the response.
If the Requester specifies a type with the Content-Type: or Accept: headers that is not valid (i.e. -it's not one of the three media types listed above) then an error is generated (probably a 415 HTTP error response code.)
Supported Content Encodings
Either the requester or the responder may use the Content-Encoding: header to indicate that the contents of a message have been encoded prior to transmission. The only supported Content-Encoding parameter is:
What Happens When
I Don't Care What Media Type a Response Uses?
If you are requesting a service from an OGP protocol endpoint, and you do not care which of the three media-types is used for return data, use the header 'Accept: */*'. Or, you may choose to omit the Accept: header all-together.
I Want a Particular Media Type in Response
If you are requesting a service from an OGP protocol endpoint, and you want a particular media-type in return, use the Accept: header to specify the media type. If you specify a media type the service cannot produce, an error will be generated (again, probably a 415 HTTP error response code.)
Why Doesn't It Work This Way
If it doesn't work this way, it means our implementation is broken. please file a JIRA.