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 (only GET is allowed, if omitted)
• 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", "type": "application/vnd.genesis.Project+json", "rel": "collection"},
    {"href" : "/settings", "type": "application/vnd.genesis.Link+json", "rel": "collection"}
]

GET / (no admin privileges)

[
    {"href" : "/projects", "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", "rel" : "self", "type": "application/vnd.genesis.Project+json"}
            ]
        },
    ],
    "links": [
       {"href":"/projects", "method": ["post"], "rel":"create", "type" : "application/vnd.genesis.Project+json"} 
    ]
}

GET /projects (no admin privileges)

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

For non-admin user no links array will be present, so user can't create projects.

• User goes to /projects/1/settings

GET /projects/1 with admin privileges

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

GET /projects/1 without admin privileges

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