Link relations to specify how to handle a URL returned from a API

[Motti Cc]

Our product needs to message users within our app every so often to prompt them to perform a particular action.

The message is a plain text message with a button and associated URL. The user sees the message and and action (typically a button/link) which they can click. If the button is clicked the client should either:

* POST/PUT/GET etc. the URL and optionally report back any failure to the user (e.g. via modeless "toast" notification)

* or, for some actions, the URL should be opened by the system (typically the default web browser, but it could be a mailto: link or something else).

Typical messages and associated action when the button is clicked are:

1. Verify your account (action URL is a POST to an API for triggering a email verification resend)

2. Rate our app (action URL is a app store link, handled by smartphone)

3. Here's how to use a particular feature (URL is a link to a help/support page)

In order to distinguish between internal API calls and URLs that should be handled by the operating system we were considering using the link relation (rel) attribute, e.g. rel="system" and rel="api".

What do you think? Comments on the general scheme also welcome.

Here's a typical message:

[

  {

    "messageId": "not.verified.message",

    "message": "Your account is not yet verified. Please click on link in email to confirm your email address.",

    "actions": [

      {

        "actionText": "Resend email",

        "href": "/api/v2/messages/not.verified.message/seenstatus"

        "rel": "seenstatus"

        "methods": "POST"   /* or PUT not potentially allow for multiple methods but in practice I think we'd only ever specify one*/

      },

      {

        ...

      }

    ]

  },

  {

    ...

  }

]

Btw we didn't go with something like http://stateless.co/hal_specification.html because we wanted something more compact and here the messages are quite simple and don't have overlap with the rest of our RESTful resources.