Parameters in API Console / Mock responses


#1

I think I know the answer to the first question, however here’s the scenario;

  • I have various endpoints, and each one has a trait that adds a parameter of ‘showAllDescendants’… Which is as it sounds, if false, you get the entities at that level, but my data structure is hierarchical, so if this is set to true, each element will contain its child elements, and so on… to the bottom of the hierarchy.

Basically, it’s difficult to represent in RAML since the example JSON will either be the top level, or the full tree.

Is there a pattern to represent this in RAML?

Is there a way to implement different responses depending on parameters?

Or even… Is there a better way to design this!?

Thanks in advance !


#2

I can see how that would be hard to represent in RAML. You could go the path of defining a schema which is a superset of both possible responses - ?showAllDescendants=true and =false, but that won’t help you on the example front. To me, this feels like it’s a bit of an anti-pattern.

One design solution is to use custom media types in order to differentiate the single-level entities and the full-depth entities. In RAML, this would allow you to define that on a single resource/method, it will behave differently depending on the media type submitted/requested - essentially, the media type replaces the query parameter, and a client can always inspect the media type in a response to understand if it is receiving the single-level or full-depth resource. You can then document requests and responses independently for each media type, within that same resource. I should mention that fine-grained media type usage like this is hotly debated within the HATEOAS community, so you should do some reading to get different sides of the argument, and YMMV.

I should mention that we’ve discussed adding the ability to include multiple examples for a method, and I expect that will happen in the not too distant future. We’ve also discussed input-response mapping, but it gets complex really quickly. It’s certainly desirable, but we haven’t found a good approach yet. If you have any suggestions around this, I’m sure @usarid and the rest of the workgroup would love to hear them.

Hope that helps!


#3

Thanks very much for your reply! It’s given me a few thinks to think about, as well as read up on! The media-type is interesting, as I have never seen anything on this before.

In this case the definition is technically correct, and it would be fine to either include or exclude the descendants in the example… since its just that, an example. But like you say, having > 1 example would probably make this perfect !

When it comes to the Mock service, In my case (Possibly many others) I’m either using the Mock service to gain sign-off for a design, or even develop against, so I can imagine one day it might be nice to have some sort of scripting or conditional returns.

In the meantime I may look into generating a mock service from RAML and using flags in the schema to determine if an element is dependant on a param.