I’m describing my json API in RAML and recently noticed that in some cases I will need to provide multiple schemas and examples for some endpoints. There is two such cases when I need to describe my API:
First case is when I’m sending POST request to endpoint and some of payload params determines response structure. Real word example: let’s say that param is
account_type. Business account type can hold additional fields like VAT number etc, while Personal account type will have its username and other fields.
Second case is when I want to include some additional relations to resource. Let’s say I have /classifieds endpoint. I can include additional data ( relations ) to it by adding some query params like user, category, etc: /classifieds?include=user or classifieds?include=category or even both: classifieds?include=user,category. It’s obvious that in such cases examples and schemas will be different.
My considerations: For second scenario possible solution could be always to describe my API with maximum possible relations. However how to deal with first I’m not sure yet.
These scenarios I think is quite often in APIs however I was not able to find solution using docs or by google.