RESTful Web Services: Different XML Representation for the same resource

Question

I'm developing a REST Web Service using a XML format response and I have some problems (Really, one problem).

One of my resources has some final fields so once they're created, they can't be modified. According to that, I need different representations for this resource depending on what I'm doing: Creating or modifiying it.

What should I do, give to the user different XML-Schemas for the same resource or write just one XML-Schema and read some fields or not depending on the method I'm being requested??

Thanks

Answer 1

What should I do, give to the user different XML-Schemas for the same resource or write just one XML-Schema and read some fields or not depending on the method I'm being requested??

If you want to reuse parts of a schema, then you can import those parts from a different file, or write a code on the server side language to reuse it. I think it is better to reuse fields with a server side language, because it is more flexible.

Answer 2

From your description, I don't see that as two representations of a resource. I see it as one resource that varies over time.

Answer 3

Sounds like your question is about documentation — what's the best way to communicate the different rules for acceptable representations depending on the state of the resource, or rather, whether it exists or not.

If that's the case, and you're using W3C XML Schema (XSD) files for documenting your representations, then I recommend a single XSD file, which would allow the fields, but add xsd:annotation children to the fields in question, and note there that those fields are only allowed when creating a new resource, not when modifying an existing resource.

You can then use the same XSD for validating both use cases, and have a few lines of code to specifically check for the immutable fields, and reject the request if the user tries to change them. This is really important; documentation matters but having a system give useful feedback is even more important. If someone tries to change one of the immutable fields, return a '400 Bad Request', and in the response body, include a clear human-readable explanation of the problem.