RESTful Web服务：记录同一资源的XML

Question

I'm using the W3C XML Schema (XSD) for documenting resources. Today, XML representation is returned in a handful of resources. A POST operation on one of my resources requires XML from the client. The response for this resource is XML. My question is as follows:

a) Should I create one XSD to handle request (POST), response for the resource?

b) If a single XSD is being used, how should I differentiate between request (POST) and responses? One thought surrounds:

<stream>
  <request>
    <items>xxx</items>
  </request>
  <response>
    <stuff>xxx</stuff>
  </response>
</stream>

Trouble is, I fear the request/response tags reflect an RPC style approach.

c) With regards to POST operations, I'd like to inform client that XML is required and is only allowed during POST operations. I suspect if this requirement is violated my best option is to return a 400 bad request? Beyond that, I think my only option with respect to my XSD is 'documenting via comments the requirement'? Just trying to get a feel for any XSD design options I should consider besides comments. Of course the challenge with one XSD is a response to a GET operation - which does not require a XML from the client - will require the client to 'ignore' the POST content in the XML.

Thanks in advance

Answer 1

a) creating one XSD and defining multiple types within that XSD is fine. It seems reasonable to me to define a request/response pair in a single XSD. Keep in mind the consumers or users of the XSD. Who will it be? Do you expect the users of your API to employ that XSD to construct apps, or will it be used only by the server (Receiving) side in order to validate requests as they come in?

In many cases, the messages that get exchanged in a REST api are not formally defined in a schema document. Instead they are documented in an html page, and then companies provide an API test page, where they can see example requests and responses. It's a very pragmatic way of documenting APIs. For an example of this, see https://api.stackexchange.com/docs/answers .

---

b) To differentiate between request and response I suppose you would use distinct element types in the XSD. Maybe I am not understanding the question.

---

c) Returning 400 is entirely reasonable, if the request is the wrong content-type, does not include an XML document, or the XML document does not conform to the required schema. If you do return a 400, it's a good idea to also return a message body, with an XML document that gives more information:

<response> 
  <error>
    <code>101.4.c</code>
    <description>your request did not include an XML document</description>
    <link>http://example.com/errorinfo?code=101.4.c</link> 
  </error>
</response> 

For more on REST API design, see http://dinochiesa.net/?p=192