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
API Explorer reserved DTO object names