What is Hypermedia API (Part 2): One of the Types of API

A hypermedia API allows clients to discover resources and available actions through links included directly in API responses. Instead of relying only on hardcoded endpoint structures, the client can use these hypermedia controls to understand where it can navigate next. This approach is closely associated with HATEOAS (Hypermedia as the Engine of Application State), one of the constraints of REST architecture.

API design and discoverability have become increasingly important as organizations rely more heavily on APIs. According to the Postman 2025 State of the API Report, 82% of organizations have adopted an API-first approach to some degree. REST also remains the dominant API architecture, used by 93% of respondents.

However, API consumers still face significant discovery and documentation challenges. The same Postman research found that 55% struggle with inconsistent documentation, while 34% have difficulty finding existing APIs. These problems make predictable API structures, clear relationships between resources, and machine-readable navigation increasingly valuable.

This is where hypermedia can help. A hypermedia-driven API includes links and relationships within its responses, allowing clients to discover related resources and supported actions at runtime. As a result, developers can reduce their dependence on hardcoded navigation between endpoints and build API clients that adapt more easily as an API evolves.

However, there is no single hypermedia format for every API. HAL, JSON-LD, Collection+JSON, and other approaches represent relationships and actions differently. In this guide, we explain how hypermedia APIs work, explore the main formats, compare their benefits and limitations, and examine where hypermedia fits into modern API development.

What Is a Hypermedia API?

A hypermedia API is an API that includes links and other hypermedia controls in its responses. These controls tell the client which related resources or actions are available next. Instead of hardcoding every possible endpoint into the client, developers can use information returned by the API to navigate between resources.

This approach is closely related to HATEOAS, or Hypermedia as the Engine of Application State. HATEOAS is a constraint of REST architecture in which the server provides information about possible state transitions as part of its responses. Therefore, the client can discover available actions dynamically rather than relying entirely on predefined URI structures.

Hypermedia Controls and Link Relations

Hypermedia controls can represent links to related resources, available operations, or possible next steps. A response might include relations such as self, next, or links to related entities. The relation gives the client context about what the linked resource represents.

For example, an API response for an order could include a link to the customer who placed it and another link to its shipment. The client can follow these relationships instead of constructing each resource URL itself. As a result, the server has more flexibility to evolve its URI structure without forcing clients to hardcode every navigation path.

However, hypermedia does not make every API automatically interoperable. A client still needs to understand the media type, link relations, and application-specific semantics used by the API. Likewise, a hypermedia API does not eliminate the need for clear API documentation. Instead, hypermedia can make navigation and available actions more discoverable at runtime.

Hypermedia Types and Formats

Developers can represent hypermedia in several ways. An API can use an established media type or define conventions that fit its application requirements. Existing formats provide standardized structures for representing links, relationships, and other metadata, which can reduce the need to create a completely custom response model.

Among the best-known approaches are HAL (Hypertext Application Language), JSON-LD, and Collection+JSON. They solve different problems and represent hypermedia in different ways. Before comparing these formats, however, it is useful to see how hypermedia works in an actual API request and response.

HAL in a Hypermedia API

HAL (Hypertext Application Language) is a format for representing resources and their relationships through hyperlinks. In a hypermedia API, HAL adds a predictable structure for links while keeping the resource data itself easy to read as JSON or XML.

A HAL response typically separates resource properties from hypermedia controls. In JSON, the _links object contains links to the current resource and related resources. HAL can also use _embedded to include related resources directly in a response.

For example, an eCommerce API could return an order together with links to its customer, shipment, and related resources:

{
  "_links": {
    "self": {
      "href": "/orders/523"
    },
    "customer": {
      "href": "/customers/128"
    },
    "shipment": {
      "href": "/shipments/873"
    }
  },
  "currency": "USD",
  "status": "shipped",
  "total": 10.20
}

Here, the self relation identifies the current order resource. The customer and shipment relations tell the client where it can find related data. Therefore, the client does not need to construct those URLs from predefined URI patterns.

One advantage of HAL is its relatively small addition to a standard JSON representation. Developers can keep their application data while adding links in a consistent structure. This makes HAL useful when an API needs straightforward resource navigation without introducing a more complex semantic data model.

However, HAL defines how an API represents links rather than the complete business semantics behind them. Clients still need to understand what relations such as customer or shipment mean. Therefore, HAL improves discoverability but does not replace API documentation or application-specific conventions.

For technical details, see the JSON Hypertext Application Language (HAL) specification.

JSON-LD for Hypermedia and Linked Data APIs

JSON-LD (JSON for Linking Data) is a W3C standard for expressing linked data in JSON. It adds machine-readable meaning to familiar JSON structures, allowing applications to identify entities, properties, and relationships more explicitly.

Unlike HAL, which primarily provides a consistent structure for links between API resources, JSON-LD focuses strongly on semantics. It uses keywords such as @context, @id, and @type to define what data represents and how individual entities relate to shared vocabularies.

For example, an eCommerce application could describe a product and its brand using linked data:

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "@id": "https://example.com/products/123",
  "name": "Wireless Headphones",
  "sku": "WH-123",
  "brand": {
    "@type": "Brand",
    "@id": "https://example.com/brands/45",
    "name": "Example Brand"
  }
}

Here, @context defines the vocabulary used to interpret the data. The @type property identifies the resource as a product, while @id provides a unique identifier for the resource. The same mechanism can describe relationships between products, brands, organizations, offers, and other entities.

One important advantage of JSON-LD is that developers can add linked-data semantics to JSON-based systems without replacing JSON itself. However, adopting JSON-LD still requires applications to understand the vocabulary and semantic model used by the API. Therefore, it is especially useful when machine-readable meaning and relationships between data are important.

For detailed information about its processing model, syntax, contexts, identifiers, and relationship with RDF, see the W3C JSON-LD 1.1 specification.

Collection+JSON for Hypermedia APIs

Collection+JSON is a JSON-based hypermedia type designed for working with collections of resources. It provides a structured way to represent lists, links, queries, and templates for creating or updating items within a collection.

The format is particularly focused on collection-oriented interactions. A Collection+JSON document can contain items, links to related resources, query definitions, and a template that describes the data a client can submit when adding or editing an item.

For example, a Collection+JSON template could describe the fields required to create a product. Using typical eCommerce product data, such a representation might look like this:

{
  "name": "Bag",
  "model": "bag_01",
  "description": "Product description",
  "price": 99.9,
  "sku": "bag_01",
  "short_description": "Short description. This is very short description",
  "type": "simple",
  "status": "disabled",
  "visible": "search",
  "category_id": "6",
  "categories_ids": "23,56",
  "product_class": "Shirts",
  "product_type": "BICYCLE",
  "is_virtual": false,
  "downloadable": false,
  "is_supply": true,
  "available_for_view": true,
  "available_for_sale": true,
  "store_id": "1",
  "stores_ids": "1,2",
  "lang_id": "3",
  "old_price": 99.9,
  "special_price": 56.9,
  "wholesale_price": 56.12,
  "cost_price": 65.9,
  "fixed_cost_shipping_price": 5.5,
  "tier_prices": [
    {
      "quantity": 0,
      "price": 0
    }
  ],
  "group_prices": [
    {
      "group_id": "string",
      "price": 0,
      "qty": 0
    }
  ],
  "buyitnow_price": 65.9,
  "reserve_price": 65.9,
  "measure_unit": "Piece",
  "unit_price": 10.5,
  "prices_inc_tax": false,
  "retail_price": 6.9,
  "quantity": 0,
  "in_stock": true,
  "manage_stock": false,
  "warehouse_id": "1",
  "backorder_status": "true",
  "min_order_quantity": 1,
  "max_order_quantity": 1,
  "low_stock_threshold": 1,
  "weight": 0,
  "weight_unit": "lb",
  "width": 56.12,
  "height": 56.12,
  "length": 56.12,
  "dimensions_unit": "cm",
  "barcode": "9770317847001",
  "upc": "9770317847001",
  "ean": "5901234123457",
  "isbn": "9783161484100",
  "gtin": "12345678912345",
  "mpn": "9770317847001",
  "asin": "97703178470",
  "product_reference": "5901234123457",
  "external_product_link": "http://example.com/t-shirt",
  "harmonized_system_code": "123456",
  "country_of_origin": "123456",
  "manufacturer": "Samsung",
  "manufacturer_id": "1",
  "manufacturer_info": {
    "name": "string",
    "address": "string",
    "phone": "string",
    "email": "string"
  },
  "brand_name": "Abidas",
  "image_url": "https://docs.api2cart.com/img/logo.png",
  "image_name": "abibas.png",
  "additional_image_urls": [
    "https://example.com/"
  ],
  "files": [
    {
      "name": "string",
      "url": "string"
    }
  ],
  "size_chart": {
    "id": "string",
    "url": "string"
  },
  "related_products_ids": "4,5",
  "up_sell_products_ids": "4,5",
  "cross_sell_products_ids": "4,5",
  "attribute_set_name": "Default",
  "attribute_name": "Color,Manufacturer",
  "search_keywords": "key1,key2,key3",
  "tags": "tag1,tag2",
  "materials": "materials[0]=Aluminum&materials[1]=Brass",
  "certifications": [
    {
      "id": "string",
      "images": [
        {
          "url": "string"
        }
      ],
      "files": [
        {
          "url": "string"
        }
      ]
    }
  ],
  "specifics": [
    {
      "name": "string",
      "value": "string",
      "values": [
        "string"
      ],
      "used_for_variations": false,
      "scale_id": null,
      "input_value": null,
      "food_details": {
        "calories": 0
      },
      "group_products_details": [
        {
          "id": "string",
          "quantity": 1
        }
      ],
      "booking_details": {
        "location": "string",
        "type": "date",
        "session_duration": 0,
        "session_gap": 0,
        "sessions_count": 0,
        "time_strict_value": 0,
        "time_strict_type": "days",
        "availabilities": [
          {
            "day": "sunday",
            "is_available": true,
            "times": [
              {
                "from": "09:00",
                "to": "21:05"
              }
            ]
          }
        ],
        "overrides": [
          {
            "day": "sunday",
            "date": "2033-11-02"
          }
        ]
      }
    }
  ],
  "avail_from": "2029-10-25T15:54:37-0500",
  "sprice_create": "2018-08-25 23:56:12",
  "sprice_modified": "2018-12-05 13:46:20",
  "sprice_expire": "2018-08-25 23:56:12",
  "created_at": "2014-08-09 13:13:13",
  "auto_renew": false,
  "when_made": "made_to_order",
  "meta_title": "category,test",
  "meta_keywords": "category,test",
  "meta_description": "category,test",
  "url": "/product_slug",
  "seo_url": "some seo url",
  "tax_class_id": "9",
  "taxable": true,
  "sales_tax": {
    "tax_percent": 0,
    "tax_state": "string",
    "shipping_inc_in_tax": true
  },
  "condition": "Like New",
  "condition_description": "Almost perfect condition, a few scratches",
  "allow_display_condition": false,
  "payment_methods": "payment_methods[0]=CashOnPickup&payment_methods[1]=PayPal",
  "paypal_email": "[email protected]",
  "shipping_template_id": 0,
  "processing_profile_id": "`12345678`",
  "shipping_details": [
    {
      "shipping_type": "string",
      "shipping_service": "string",
      "shipping_cost": 0
    }
  ],
  "is_free_shipping": true,
  "delivery_code": "24uurs-23",
  "delivery_type": "PARCEL",
  "delivery_time": 1,
  "delivery_option_ids": "6956548250505111111,6956548250505111112",
  "package_details": {
    "measure_unit": "string",
    "weigh_unit": "string",
    "package_depth": 0,
    "package_length": 0,
    "package_width": 0,
    "weight_major": 0,
    "weight_minor": 0,
    "shipping_package": "string"
  },
  "logistic_info": [
    {
      "logistic_id": 0,
      "is_free": true,
      "shipping_fee": 0,
      "size_id": 0
    }
  ],
  "listing_duration": "Days_3",
  "listing_type": "FixedPrice",
  "category_type": "Apparel",
  "return_accepted": true,
  "seller_profiles": {
    "shipping_profile_id": "string",
    "payment_profile_id": "string",
    "return_profile_id": "string"
  },
  "auction_confidentiality_level": "public",
  "best_offer": {
    "minimum_offer_price": 0,
    "auto_accept_price": 0
  },
  "production_partner_ids": "4,5",
  "marketplace_item_properties": "{\"color\":[\"Silver\"],\"manufacturer\":\"Philips\",\"features\":[\"3 way\"],\"countPerPack\":1,\"watts\":{\"unit\":\"W\",\"measure\":40}}",
  "clear_cache": true,
  "viewed_count": 0,
  "ordered_count": 0,
  "vendor_id": "1",
  "shop_section_id": 12345678,
  "return_policy_id": "`12345678`",
  "personalization_details": {
    "is_personalizable": true,
    "personalization_is_required": true,
    "personalization_char_count_max": 0,
    "personalization_instructions": "string"
  },
  "personalization_questions": [
    {
      "question_text": "string",
      "instructions": "string",
      "question_type": "text_input",
      "required": true,
      "max_allowed_characters": 1,
      "max_allowed_files": 1,
      "options": [
        "string"
      ]
    }
  ],
  "manufacturer_ids": "1,2,3",
  "responsible_person_ids": "1,2,3",
  "idempotency_key": "098f6bcd4621d373cade4e832627b4f6"
}

The template describes the data that a client can submit when creating or updating a resource. In an eCommerce context, these fields can represent product properties such as a name, model, price, and available quantity.

This example illustrates the Collection+JSON approach rather than the actual API2Cart request format. For comparison, developers can explore the real API2Cart product.add method, which provides a unified interface for adding products to supported eCommerce platforms.

Collection+JSON differs from both HAL and JSON-LD. HAL emphasizes links and embedded resources, while JSON-LD focuses on semantic relationships between data. Collection+JSON provides a more opinionated model for interacting with resource collections through links, queries, and templates.

For the complete format structure and examples, see the Collection+JSON specification.

Conclusion: Choosing the Right Hypermedia API Approach

There is no single hypermedia format that fits every API. HAL provides a relatively simple way to represent links and related resources. JSON-LD adds machine-readable semantics and linked-data relationships to JSON. Meanwhile, Collection+JSON offers a more structured model for working with collections, queries, and interaction templates.

The right choice depends on what your hypermedia API needs to communicate. Developers should consider resource relationships, client behavior, semantic requirements, and implementation complexity. Most importantly, hypermedia should make an API easier to navigate and evolve rather than add complexity without a clear purpose.

From API Design to eCommerce Integration

For eCommerce software providers, API design is only one part of the integration challenge. SaaS applications may need to connect with multiple shopping carts and marketplaces, retrieve commerce data, and support platform-specific functionality. Building and maintaining each connection separately can increase development work as platform coverage grows.

API2Cart provides a unified API for 80+ supported eCommerce platforms and marketplaces, including Shopify, WooCommerce, Magento, BigCommerce, OpenCart, PrestaShop, and others. Software providers can use one integration layer to work with products, orders, customers, categories, shipments, and other eCommerce data.

Instead of maintaining a separate integration architecture for every supported platform, development teams can use API2Cart to expand their eCommerce connectivity through a unified interface.

Ready to explore API2Cart for your eCommerce software? Create your API2Cart account for free and start working with a unified eCommerce API.

Lexy Mayko

Marketing manager, API fan, nerd, perfectionist, British humour enthusiast, literature and history geek.