Links common

Links common information

To enable autodiscovery a new link object is introduced. Link itself must contain following attributes:

• href - Absolute (may be relative to base) uri to resource.
• rel - Link relation. May contain values:
  • self - for resources pointing to a current resources.
  • collection - to point to collection urls (GET)

Link may include:

• type - Domain type and media. This is possibly valid only for GET links.
• methods - array of HTTP verbs to use (only GET is allowed, if omitted)

Data types

Links can optionally contains information about domain type of an object. Proposed format is application/vnd.griddynamics.genesis.<Type>+<format> where Type corresponds to Genesis API type and format is a media format (only JSON currently used and supported.

Collection requests

If user get a collection link, it should have a result with an items element, containing a body of collection itself and an optional collection of links with additional collections requests parameters (if applicable) and non-GET based request that can modify collection contents.

Example

If we have url /collection to a collection of domain object /item and we can add a new item to a collection, then we have a following response when sending GET /collection request:

{
  "items": [
      {
          "id"    : "1",
          "links" : []
      }
  ],
  "links" : [{
      "href" : "/collection",
      "rel": "self",
      "methods":["get","post"],
      "type":"application/vnd.<...>.Item+json"}
  ]
}

If we can't modify content of collection, we'll get other content of a links collection:

{
  "items": [
      {
          "id"    : "1",
          "links" : [
              {
                  "rel":"self",
                  "href":"collection/1/items/1",
                  "type":"application/vnd.<...>.Item+json"
              }
          ]
      }
  ],
  "links" : [{
      "href" : "/collection",
      "rel": "self",
      "methods":["get","post"],
      "type":"application/vnd.<...>.Item+json"}
  ]
}

Item request

With requests for concrete item link with a rel: self attribute must contain all possible HTTP verbs than user can use to access item with a following semantics:

Verb	Meaning
GET	Read
PUT	Update
DELETE	Delete

If verb is not present in link methods attribute, request with this verb should results with a 403 code if user is not allowed to use this operation or 405 if operation is not supported by application.

Example

User sends a get request for concrete item.

• User can update and delete an item:

{
    "id":1,
    "links": [
        {
            "href": "/collection/1/items/1",
            "rel" : "self",
            "methods" : ["get","put","delete"],
        }
    ]
}

• User can not update neither delete an item:

{
    "id":1,
    "links": [
        {
            "href": "/collection/1/items/1",
            "rel" : "self"
        }
    ]
}

For items inside a collection methods attribute may be present to reduce REST calls, but it's not mandatory. If we'd like to force user to call concrete item, methods may be omitted to indicate that user must issue a GET request to find all methods that can be used.

Api changes

• Root Request

• Projects Request

• Project Settings

• Environments

• System Settings