Request body can have 1 of 2 different XML schemas - include schema as doc?


#1

I have to use RAML to describe an API for which 1 request can conform to 2 different XML schemas.

I obviously can’t put both schemas into 1 post: heading.

What is the appropriate way? Do I need to provide 2 post: methods, one for each schema?

Or is the best I can do to somehow embed the alternative schemas in markdown docs?

If so, how?


#2

So, if I do this using 2 post: objects the same object appears twice in the RAML2HTML output, which is no use.

I found a supposed way to make 2 schemas into one:

…but his means more work due to namespaces etc…

Anyone found an elegant solution here?


#3

Well, really the only right way to do this is to use custom media types, one for each document. That is you would have something like: application/vnd.company.xsd1.xml and application/vnd.company.xsd2.xml to specify different Accept or Content-Type headers. Then your RAML would have something like:

responses:
200:
body:
application/vnd.company.xsd1.xml:
schema: xsd1
application/vnd.company.xsd2.xml:
schema: xsd2

If it is a POST/PUT/PATCH with a body being sent in… same thing. Though, to be honest this sort of two or more different document types should only be for responses. I would suggest different resources for sending in two or more different body types on a POST/PUT/PATCH request.

In the above definition… the API consumer would pass in the Accept header one or the other media type to indicate which they want back.


#4

Thanks @Kevin_Duffey for your kind response - this sounds logical. We’d have to make our users use the headers, but I guess that’s the price of clarity.