API Explorer Nested Properties / Object

1

We are looking to use API Explorer (/ui) for some rapid prototyping and testing. We created a request object with a nested structure similar to this:

public class NestedClass 
{
    public int NestedNumber { get; set; }
    public string NestedString { get; set; }
}
[Route("/myrequest")]
public class MyRequest : IReturn<MyResponse>
{
    public NestedClass ThingA { get; set; }
    public NestedClass ThingB { get; set; }
    public string SomeText { get; set; }
}

When I browse to /ui/MyRequest I only see the field SomeText in the form. ThingA & ThingB related form fields are not present. When I browse Details and Code tab I see all the properties and nested properties.

My gut feeling is that this feature only works with flat request objects. Is there any support for nested properties with API Explorer / UI?

2

Correct, API Explorer can’t tell what control to apply to a nested complex type. Your service behaviour/contracts don’t change, but the generated UIs don’t support them.

3

Are there any plans to support them? Would a uservoice feature request be entertained, or is there some significant technical obstacle which makes this an impossibility?

4

I think the main complexity comes down to how to present such UIs with combinations of complex types, list of etc, and actually making it usable. A wall of fields is not likely to be very useful in a lot of cases when DTOs are using complex nested types.

In the cases where you have lots of optional fields which depend on other choices, you could make it cleaner, but that will come down to business knowledge rather than what can be inferred from your DTOs. In that case, overriding a view and using a custom UI is likely a better approach since you get to control it yourself.

If you have lots of endpoints with nested complex types, understandably this can be quite a lot of work to support. GitHub Discussions is also a good place to raise this and put forward options and start the discussion.

1 Like
5

There’s effectively no standard or popular conventional way to generically handle nested complex types in HTML forms which by their nature are flat structured, e.g. the POST/PATCH APIs serialize the HTML input controls into a FormData which doesn’t have any notion of handling nested complex types.

For better interoperability we also recommend maintaining a flat structure for Request DTOs so they’re more easily consumable in generic HTTP Clients or HTTP Tools like curl.

1 Like
6

I have been using api explorer to document api integration but there are several situations where it makes sense for the front end to pass a nested object or list in a request. I.e. filters, cart items etc…

I have seen similar interfaces add a heading or nested panel for nested objects. I think that would be good. I really like the new API explorer but having the request testing form incomplete makes it difficult to use for documentation or handoff as it causes confusion.

Even if it just showed nested objects as json text fields it would stop the confusion of missing properties. There needs to be some visual representation on the form of the existence of the other properties. It’s cropped up a few times for me now with front-end getting blocked because they expect form to be complete. I know its available on details tab but people are missing that.

7

You might be able to use a custom vue component with your own [Input(Type="MyCustomVueComponent")] where you can show the additional fields, and handle modelValue yourself and emits:['update:modelValue']. But you will have test on your own DTOs if this approach is going to work, as it might depend on the depth of your request DTO or the verb being used.

1 Like