API JSON nested layer after layer with long front-end field paths: should the structure be flattened?

Whether API JSON should be flattened is not judged by whether it looks good, but by whether the fields have real parent-child relationships. Attributes of the same object belong on the same layer; only genuinely one-to-many data should be split into arrays or child objects. Based on common 2026 project delivery experience, a main object nested one layer, and usually no more than two layers, falls within a maintainable range. More than three layers generally means the API should be split, or a thinner view API should be added for the front end. APIs that only serve internal scripts usually do not need to be refactored just for visual consistency.

What problem does nested API structure actually solve?

Nesting itself is not a formatting preference; it is a projection of data relationships. If an order has a set of item lines, and each item line has specification options, flattening this kind of one-to-many relationship by force would rely on field names with prefixes, such as item1_name and item2_name. The number and meaning of fields would change with the number of records, making it harder for callers to write code.

Another kind of nesting is the unified response envelope, namely the code, message, and data layer. It is different from business nesting: the former is a protocol convention, fixed and not changing with the business; the latter is the business structure. When judging whether an API structure is messy, separate these two layers first. Many front-end and back-end debates are actually about whether the protocol layer should remain.

• Protocol layer: code, message, and data are fixed and do not carry business semantics.
• Business layer: attributes of the same entity belong on the same layer, and one-to-many relationships are expressed as arrays.
• Presentation layer: converting API data into a view model is an internal front-end concern, and the API structure does not need to be changed in reverse because of it.

Deciding whether to flatten: a reusable three-check framework

If the only arguments are the front end saying field access is troublesome and the back end saying the structure is clear, the debate usually has no resolution. Based on project delivery habits, you can consistently use three checks: check the relationship, check the use case, and check the change frequency. If two or more checks point to splitting, keep the nesting; only when all three point to merging should flattening be considered.

1. Check the relationship: whether the fields are attributes of the same entity or a one-to-many relationship. The former goes on one layer; the latter uses arrays or child objects.
2. Check the use case: whether the API is for a list, a detail page, or an export. List API fields are more stable when thinner, while detail APIs can be somewhat thicker.
3. Check the change frequency: fields that often change independently should be grouped separately, while fields that change together over the long term should stay on the same layer, reducing the impact area when changes happen.

The point of the three checks is to turn debate into verification. Note that flattening does not mean deleting nesting; it means moving fields up to the parent level and keeping naming consistent. Otherwise, the same field may be called userName in the list API and name in the detail API, and integration testing will again spend time aligning fields.

Nested structure vs. flat structure

There is no universal answer between structures. You can set a verifiable scale along the following dimensions before deciding whether to change anything.

• Readability: a one-layer structure lets newcomers access fields directly; three or more layers generally require documentation plus examples to understand.
• Front-end cost: each additional nesting layer usually adds several to a dozen branches for value access and null checks, and empty data must be confirmed layer by layer.
• Extensibility: flat structures have a smaller change surface when adding fields, but when fields on the same layer reach 15~20 or more, naming conflicts and overlapping meanings become more likely.
• Compatibility: removing fields is usually backward compatible, while changing nesting to flat is a breaking change, and old clients may go blank directly.
• Transfer size: APIs with fewer fields and shallower layers commonly fall within a typical range of 10% to 30% smaller than a three-layer structure with the same data; after compression, the difference narrows.

This comparison is not meant to make everyone choose flat. It is a reminder of one thing: any change involving field paths should be handled through API versioning. If you can add an adaptation layer in a new version and keep old fields for a period, do not directly change the old fields, or the cost is often borne first by online users.

Delivery reality: when the structure changes, where does rework concentrate?

In one project delivery, two or three weeks after the API went live, the front end said the fields were too deep and wanted them flattened. The constraints at the time were: three pages already used the old structure, the mobile side still had an unreleased branch, and only two days remained in the schedule. A relatively safe approach was to open a new version path, keep the old fields for one to two release cycles, let new pages use the new structure first, and maintain two synchronized copies of the API documentation and mock.

The cost of doing so is that the old structure needs extra maintenance for a period. Based on the typical range, the extra work is about one to two days; compared with directly changing old fields and causing online blank screens, this is usually more cost-effective. Rework usually concentrates in three places: front-end type definitions, field names in analytics events, and API documentation examples. Listing these three places before changing the structure can save a lot of back-and-forth confirmation.

Common pitfalls and acceptance criteria

When it comes to acceptance, the quality of a structure can be judged by just two things: whether a newcomer can directly write field access code using the documentation; and whether the API and front end throw errors when data is empty or fields are missing. If these two cannot be met, even a neat structure is a burden.

• Putting all return values inside data, with business fields nested another two or three layers below.
• Fields with the same meaning having different names in different APIs, forcing the front end to remember mappings.
• Using null and missing fields to express the same kind of empty value, branching the null-check logic.
• Nesting arrays inside array elements without stable IDs, so the front end can only merge data by index.

For acceptance, you can consistently test three types of data: one normal record, one where the main data exists but the child array is empty, and one where the child object is entirely missing. Check whether field paths and default values meet expectations. This kind of check is a fixed item in the delivery acceptance checklist; go through it item by item according to each client's type definitions and the API documentation. There is no need to build extra tooling for it.

Applicable scenarios and boundaries where it does not apply

Structure adjustments are usually worth doing for business APIs shared across multiple clients and whose fields will be iterated over the long term, such as order lists, product details, and user centers. The criterion can be simpler: this API will still be changed at least twice within a year, and it has more than one caller.

Another category is neither suitable nor necessary: APIs used only by one internal script or for one-off data verification, with a lifecycle that may last only a few days. For these APIs, it is enough to gather the fields and make them work; designing nesting levels for them spends time on something that will not be reused. Another boundary is strong transactional calls between internal services, where field stability comes first and the structure does not need to be changed for reading experience.

FAQ

How many layers of API field nesting are appropriate?

Based on common 2026 delivery experience, a main object nested one layer, and usually no more than two layers, falls within a maintainable range. At three or more layers, it generally means the API should be split, or a thinner view API should be added.

Will changing a nested structure to flat affect an already released app?

Yes. Removing fields is usually backward compatible, but changing field paths is a breaking change. A common practice is to keep old fields for one to two release cycles and then remove them after old version coverage drops.

If the front end converts a layer of structure itself, does the back end not need to change?

For a small scope, yes. When multiple clients share the API or fields are iterated over the long term, each client writing its own conversion tends to drift further apart, and integration cost becomes higher instead.

Must list APIs and detail APIs have the same structure?

They do not have to be forced to match. List API fields can be thinner and shallower, while detail APIs can be somewhat thicker, but the naming and meaning of the same field should be consistent.

At how many fields on the same layer should grouping be considered?

The experience range is that when a layer exceeds 15~20 fields, naming conflicts and overlapping meanings become more likely; grouping by meaning can be considered, but there is no need to add a meaningless wrapper layer just for grouping.

If you are stuck on a structure problem, start with the API that has been changed twice recently. Run the three checks over its fields, adjust only the one place with obvious front-end impact, ship it through a new version path, and observe for one release cycle. Structure optimization addresses the time cost of each future change. If this API itself rarely changes again, keeping the status quo is usually the more cost-effective choice.