12 Partial Representations

title: Partial Representations in HATEOAS APIs weight: 22 date: 2026-06-28 lastmod: 2026-06-28 description: Implement partial representations in HATEOAS APIs using sparse fieldsets and embedded resource depth control for performance optimization without losing hypermedia navigation. tags: [api-development, hateoas]

Partial representations allow clients to request specific fields and control embedding depth using query parameters like ?fields=id,name,price and ?embed=customer.address, while retaining hypermedia links for navigation.

```python
from flask import request

@app.route("/api/orders/<order_id>")
def get_order(order_id):
    order = get_order_by_id(order_id)

    # Field selection
    fields = request.args.get("fields", "").split(",")
    if fields and fields[0]:
        result = {k: v for k, v in order.items() if k in fields}
    else:
        result = dict(order)

    # Always include links (even in partial responses)
    result["_links"] = build_links(order)

    # Embed depth control
    embed = request.args.get("embed", "none")
    if embed == "customer":
        result["_embedded"]["customer"] = get_customer(order["customer_id"])
    elif embed == "all":
        result["_embedded"]["customer"] = get_customer(order["customer_id"])
        result["_embedded"]["items"] = get_order_items(order_id)

    return jsonify(result)

What's Next

Now learn about HATEOAS vs GraphQL in Hypermedia APIs and HATEOAS.