Discussion: would it make sense to combine @links and @link-templates into one construct?

[vtsukur]

@link-templates and @links serve the same goal with the only distinction in the absence or presence of a template nature. Would it make more sense to treat templating a characteristic of a link, not a separate construct?

Here is what I mean:

@links: {
  self: {
    href: "http://mason-issue-tracker.cbrain.net/resource-common"
  },
  is:contact: {
    href: "http://mason-issue-tracker.cbrain.net/contact",
    title: "Complete contact information in standard formats such as vCard and jCard"
  },
  is:issue-query: {
    template: "http://mason-issue-tracker.cbrain.net//issues-query?text={text}&severity={severity}&project={pid}",
    title: "Search for issues",
    description: "This is a simple search that do not check attachments.",
    parameters: [
      {
        name: "text",
        description: "Substring search for text in title and description"
      },
      {
        name: "severity",
        description: "Issue severity (exact value, 1..5)"
      },
      {
        name: "pid",
        description: "Project ID"
      }
    ]
  }
}

Alternative is just to treat href attribute as potentially templated and provide parameters when it is templated:

@links: {
  ...
  is:issue-query: {
    href: "http://mason-issue-tracker.cbrain.net//issues-query?text={text}&severity={severity}&project={pid}",
    title: "Search for issues",
    description: "This is a simple search that do not check attachments.",
    parameters: [
      {
        name: "text",
        description: "Substring search for text in title and description"
      },
      {
        name: "severity",
        description: "Issue severity (exact value, 1..5)"
      },
      {
        name: "pid",
        description: "Project ID"
      }
    ]
  }
}

[JornWildt]

I understand what you mean, thanks, I have been thinking the same myself.

Question: can you think of a use case where it would make more sense to combine links and link templates?

[vtsukur]

Let's see :)

@links in Mason are mapped to outbound navigational links (LO) in H-factors specification.

@link-templates satisfy the requirement of templates queries (LT) in the very same specification.

Template queries (LT) is not a conceptually different thing, it is an extension to LO. Introducing new top-level construct like @link-templates in the resource representation suggests a bigger difference between them, but is it worth the small difference? Especially, taking into account that they share other arguments like title and media type.

Having unified structure for representing query links (LE, LO and LT in H-factors is more visually appealing. Query nature of the links (GET for HTTP use case) is an important grouping concept, templating is a detail.

Imagine an entry point resource that has a self reference and a templated link to sub-resources (this is a use case in my project):

GET http://server/api/objects
{
  "@links": {
    "self": {
      "href": "http://server/api/objects"
    }
  },
  "@link-templates": {
    "object:item": {
      "template": "http://server/api/objects/{id}",
      "title": "Fetches object by the given ID",
      "parameters": [
        {
          "name": "id",
          "description": "Unique identifier of the object"
        }
      ]
    }
  }
}

This looks more unified:

GET http://server/api/objects
{
  "@links": {
    "self": {
      "href": "http://server/api/objects"
    },
    "object:item": {
      "href": "http://server/api/objects/{id}",
      "title": "Fetches object by the given ID",
      "parameters": [
        {
          "name": "id",
          "description": "Unique identifier of the object"
        }
      ]
    }
  }
}

It is a different story with @actions though. Actions (usually) represent non-idempotent or idempotent update operations (LN, LT) that are different in nature and thus it makes more sense for them to have a separate construction.

BTW some hypermedia standards even discard this difference in favor of unification, e.g. UBER by Mike Amundsen.

[JornWildt]

The version 2 specification will combine all links, link templates and actions into a single object. Right now the name is "@navigation" but I am looking for something better.