Accessing T-Plan Nodes

The Basics

Once you have successfully logged into the API, you will probably need to access nodes within the T-Plan hierarchies. In order to avoid having to externally "guess" URIs to Nodes in the hierarchy, it's generally best to use the root links provided when you first log into the API.

    "_links": {
      "analyze": {
        "href": "http://localhost:8080/api/v1/nodes/analyze"
      },
      "design": {
        "href": "http://localhost:8080/api/v1/nodes/design"
      },
      "manage": {
        "href": "http://localhost:8080/api/v1/nodes/manage"
      }

These references will take you to the root nodes of each of the modules in T-Plan.

Working with Nodes

Nodes can be requested individually by Id (or Number), or as a collection of child nodes of a given parent. Nodes are retrieved by sending a GET request to the /nodes resource, passing the Id of the node as a URI segment if you are requesting an individual node, or a query if you are requesting by Parent or Number.

A successful response to the request follows the same form, regardless of query mechanism - an array of one or more nodes that satisfy the query.

Here is an example of a GET request for the node with Id "6F1204886EF340E88BAD68B46568D719":

http://localhost:8080/api/v1/nodes/6F1204886EF340E88BAD68B46568D719

The request should have the x-access-token header set to the JWT token issued during authentication. Assuming a valid request, the response might look something like this:

{
  "status": "success",
  "data": [
    {
      "id": "6F1204886EF340E88BAD68B46568D719",
      "idex": "",
      "name": "Win 2000 & IE 6.0",
      "description": "",
      "entityid": "D7DC8291E8A411D08C7E0000C0D9D069",
      "entityname": "TestSuite",
      "parentid": "4A74CF03850C44ADB8070827154BAF91",
      "createdby": "SysAdmin",
      "createdon": "2003-03-12T22:38:42.000Z",
      "lastmodifiedby": "SysAdmin",
      "lastmodifiedon": "2003-03-12T22:38:47.000Z",
      "version": "",
      "number": 96,
      "module": "Manage",
      "haschildren": 1,
      "_links": {
        "self": {
          "href": "http://localhost:8080/api/v1/nodes/6F1204886EF340E88BAD68B46568D719"
        },
        "parent": {
          "href": "http://localhost:8080/api/v1/nodes/4A74CF03850C44ADB8070827154BAF91"
        },
        "children": {
          "href": "http://localhost:8080/api/v1/nodes?parentid=6F1204886EF340E88BAD68B46568D719"
        },
        "results": {
          "href": "http://localhost:8080/api/v1/results/6F1204886EF340E88BAD68B46568D719"
        },
        "stats": {
          "href": "http://localhost:8080/api/v1/statistics/6F1204886EF340E88BAD68B46568D719"
        }
      }
    }
  ]
}

As well as the node's own properties, useful links to other resources are provided in the _links section, including links to this node's children, parent and other items that might be dependant on the type of node. These links provide a means of navigating the hierarchy without having to predict in advance, the URIs of those nodes.

In the example above, the "children" item in the _links section gives an example of a URI for requesting a collection of nodes by parent id. This will return an array of one or more nodes. Note that if this link is absent, the node has no children.

Creating Nodes

You can create new nodes by sending a POST request to the /nodes resource.

You need to provide some minimal data to start with, which should be passed as JSON in the request body; the Name and Description of the item you are creating, and its entity id and its parent id.

Here's an example of a Postman request, set to create a new node in Manage:

Assuming the creation of the new node succeeds, its details are returned in the response:

{
  "status": "success",
  "data": {
    "id": "23C9F0D7105E4433B53CD0FD620DD1EF",
    "idex": "",
    "name": "My New Suite - Thu May 12 2016 11:04:17 GMT+0100 (BST)",
    "description": "This is my new Test Suite",
    "entityid": "D7DC8291E8A411D08C7E0000C0D9D069",
    "parentid": "8EE161C631864865A9F820E848B2F4DF",
    "createdby": "SysAdmin",
    "createdon": "2016-05-12T11:04:12.013Z",
    "lastmodifiedby": "SysAdmin",
    "lastmodifiedon": "2016-05-12T11:04:12.013Z",
    "version": "1",
    "number": 206,
    "module": "Manage",
    "_links": {
      "self": {
        "href": "http://localhost:8080/api/v1/nodes/23C9F0D7105E4433B53CD0FD620DD1EF"
      },
      "parent": {
        "href": "http://localhost:8080/api/v1/nodes/8EE161C631864865A9F820E848B2F4DF"
      },
      "children": {
        "href": "http://localhost:8080/api/v1/nodes?parentid=23C9F0D7105E4433B53CD0FD620DD1EF"
      },
      "results": {
        "href": "http://localhost:8080/api/v1/results/23C9F0D7105E4433B53CD0FD620DD1EF"
      },
      "stats": {
        "href": "http://localhost:8080/api/v1/statistics/23C9F0D7105E4433B53CD0FD620DD1EF"
      }
    }
  }
}