Thing Description for LinkSmart directory

[farshidtz]

This is an improved version of the TD presented in F2F for the LinkSmart directory.

[benfrancis]

This makes for a bit of an awkward Thing Description, with the API of the directory being shoehorned into being described as properties and actions.

I made my own attempt at describing a directory with a Thing Description, with the list of things as a property rather than links, and that turned out quite awkward too.

I'm beginning to wonder whether trying to describe this API in terms of properties, actions and events is actually a good idea. Thing Descriptions are not great at describing collections of resources in general.

See #34 (comment)

[benfrancis]

This is a bit of a strange example of an action because it's really several different actions, as I think is revealed by the ambiguous name. I would usually expect an action to be describable with a verb or verb phrase.

[farshidtz]

I had my concerns when mapping the OpenAPI specs to TD (see the last slide).

I agree that they are different actions, and separating them makes it clearer. However, I would keep the names equivalent to the HTTP methods, because they have their own semantics.

{
  ...
  "actions": {
    "postTD": {
      "description": "Add an anonymous Thing Description (without ID)",
      "forms": [
        {
          "href": "/td",
          "htv:methodName": "POST",
          "contentType": "application/ld+json"
          // how to specify that the response contains a system-generated id in Location header?
        }
      ]
    },
    "putTD": {
      "description": "Add or modify a Thing Description",
      "uriVariables": {
        "id": {
          "title": "Thing Description ID",
          "type": "string",
          "format": "iri-reference"
        }
      },
      "forms": [
        {
          "href": "/td/{id}",
          "htv:methodName": "PUT",
          "contentType": "application/ld+json"
        }
      ]
    },
    "patchTD": {
      "description": "Modify parts of a Thing Description",
      "uriVariables": {
        "id": {
          "title": "Thing Description ID",
          "type": "string",
          "format": "iri-reference"
        }
      },
      "forms": [
        {
          "href": "/td/{id}",
          "htv:methodName": "PATCH",
          "contentType": "application/ld+json"
        }
      ]
    },
    "deleteTD": {
      "description": "Remove a Thing Description",
      "uriVariables": {
        "id": {
          "title": "Thing Description ID",
          "type": "string",
          "format": "iri-reference"
        }
      },
      "forms": [
        {
          "href": "/td/{id}",
          "htv:methodName": "DELETE"
        }
      ]
    }
  }
  ...
}

[benfrancis]

Using URL templates in the form of a property description is also kind of odd, because it's really a collection of multiple resources which is being described rather than a single property resource.

[farshidtz]

IMO, TD has evolved for describing things and not collection services. Trying to use a TD to describe a collection API has its side effects. I decided to map "properties" to resources of the collection. I also thought about "getTD" and "listTD" as actions on the collection, but it seems contradictory to the specs because those operations don't manipulate the state of the collection.

"An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state" [1]

[benfrancis]

I agree that getTD and ListTD don't make sense as actions.