Dependency links usage in clients

This page describes the new dependency links feature in Initializr and how it can be used in clients. This resource should be useful to IDE developers, in particular.

Description

Each dependency can be associated to one or more link. Essentially, each link defines:

• A nature (or relation) that associate some semantic to the link

• The link itself (can be templated, see below)

• An optional description (or title)

Note	Links order is respected so if the client can only show one link, it should chose the first one.

Relation (rel)

The following rel value are currently officially supported:

• guide: the link points to a guide describing how to use the related dependency. It can be a tutorial, a how-to or typically a guide available on https://spring.io/guides

• reference: the link points to a section of a developer guide typically or any page that documents how to use the dependency

Link (href)

The url can be templated if its actual value can change according to the environment. An URL parameter is specified with curly braces, something like https://example.com/doc/{bootVersion}/section defines a bootVersion parameter.

The following attributes are currently supported:

• bootVersion: the Spring Boot version that is currently active

Note	If an URL defines a parameter that the client doesn’t know, it should probably ignore the link altogether

Description (title)

Each link can have an optional description that can be used when rendering the link in an UI.

If the link does not have one, clients are strongly advized to generate a default based on the relation. For instance, the default description for a link with rel reference could be "Reference Doc".

Format

Links are exposed as a _links element and are HAL-compliant. If more than one link has the same relation, they are grouped in a JSON array. Otherwise, the link is the direct child of the relation it is associated to. Here is an example:

{
  "id": "data-rest",
  "name": "Rest Repositories",
  "description": "Exposing Spring Data repositories over REST via spring-data-rest-webmvc",
  "_links": {
    "guide": [
      {
        "href": "https://spring.io/guides/gs/accessing-data-rest/",
        "title": "Accessing JPA Data with REST"
      },
      {
        "href": "https://spring.io/guides/gs/accessing-neo4j-data-rest/",
        "title": "Accessing Neo4j Data with REST"
      },
      {
        "href": "https://spring.io/guides/gs/accessing-mongodb-data-rest/",
        "title": "Accessing MongoDB Data with REST"
      }
    ],
    "reference": {
      "href": "http://docs.spring.io/spring-boot/docs/{bootVersion}/reference/htmlsingle/#howto-use-exposing-spring-data-repositories-rest-endpoint",
      "templated": true
    }
  }
}