Link Element

_{Published: 22 April 2025}

Known Uses

The Linked Element pattern is used in a few Dutch government APIs but is less common in the Dutch energy sector. Known uses include the BAG and Kadaster APIs:

1. BAG (Basisregistratie Adressen en Gebouwen) – The Basic Registration of Addresses and Buildings in the Netherlands;
2. Kadaster – The national land registry and mapping agency of the Netherlands;
   

These APIs provide up-to-date data on addresses, addressable objects, and buildings. The links in these APIs are formatted according to the HAL (Hypertext Application Language) specification.

Other known uses:
– Otto: https://api.otto.de/portal/guidelines/rest-guidelines/hypermedia
– Zalando: https://opensource.zalando.com/restful-api-guidelines/#hypermedia

Discussion Input

Due to the availability of various hypermedia formats, the Dutch government and energy sector chose HAL for hypermedia implementation because its simplicity, compared to other formats, allows for quick and easy adoption. The [HAL] standard is a universal and widely adopted standard for serializing hyperlinks in JSON responses. The Dutch government module on hypermedia provides the following guidelines:

• provide absolute URIs for hyperlinks (no relative links)
• the usage if hypermedia is not intended to implemente HATEOAS
• navigation controls are only allowed to point to other APIs when they share governance and security context

Nowadays, only a small fraction of modern web APIs fully embrace hypermedia principles, and this is certainly true for the Dutch government and energy sector. In ourenergy sector Linked elements are primarily used for implementing pagination and will also be used for lightweight (‘thin’) event notifications.

The book suggests incorporating semantics into the Link Element Pattern. Semantic links go beyond simple navigation by conveying meaning about the relationship between resources. These links not only provide a destination URL but also help the consumer understand the context of the link and what the next step or related resource might be. In APIs, semantic links describe relationships between resources using well-defined semantics. For example, in HAL, JSON-LD, or Atom feeds, a link with “rel”: “next” indicates the next page in pagination. This helps users and systems understand the link’s purpose and how it fits within the larger context of the application.