Links (proposal)

Links formats

New domain object Link is intoduced. Link must include following attributes:

• href - Absolute (may be relative to base) uri to resource.
• method - array of HTTP verbs to use
• rel - Link relation. May contain values:
  • self - for self-pointing resources
  • collection - to point to collection urls (GET)
  • create - for create requests (POST)

Link may include:

• type - Domain type and media. This is possibly valid only for GET links.

Example protocol

Parts of entities are omitted for the sake of brevity.

• User starts with a root of application.

GET / (admin privileges)

[
    {"href" : "/projects", "method": ["get"], "type": "application/vnd.genesis.Project+json", "rel": "collection"},
    {"href" : "/settings", "method" : ["get"], "type": "application/vnd.genesis.Link+json", "rel": "collection"}
]

GET / (no admin privileges)

[
    {"href" : "/projects", "method": ["get"], "type": "application/vnd.genesis.Project+json", "rel": "collection"}
]

Setting has a type genesis.Link, because it's anything but links collection.

For non-admin user no /settings url will be present at this stage.

• User choose to continue with /projects link

GET /projects (admin privilieges)

{    "items" : [
        {
            "name" : "project",
            "id" : "id",
            "links" : [
                {"href" : "/projects/1", "method" : ["get", "put", "delete"], "rel" : "self"},
                {"href" : "/projects/1/settings", "method": ["get"], "type": "application/vnd.genesis.Link+json", "rel": "collection"}
                {"href" : "/projects/1/envs", "method" : ["get"], "type": "application/vnd.genesis.Environment+json", "rel": "collection"}
            ]
        },
    ],
    "links": [
       {"href":"/projects", "method": ["post"], "rel":"create"} 
    ]
}

GET /projects (no admin privileges)

{  
  "items" : [
        {
            "name" : "project",
            "id" : "id",
            "links" : [
                {"href" : "/projects/1", "method" : ["get"], "rel" : "self"},
                {"href" : "/projects/1/envs", "method" : ["get"], "type": "application/vnd.genesis.Environment+json", "rel": "collection"}
            ]
        },
    ]
}

For non-admin user no links array will be present, as user can't create projects. In items element no links with rels update and delete and no link with url /projects/1/settings

• User goes to /projects/1/settings