TeamForge EventQ HTTP API for Tool Creation and Viewing

Overview

  • TeamForge EventQ HTTP API for Tool provides a means to create an Tool or view a tool. The API supports both data retrieval and submission.
  • Authentication: requires a valid TeamForge session id, passed with the 'X-EventQ-Session' header field. One way to acquire this session id is to programmatically log into TeamForge using TeamForge SOAP API.
  • Authorization: requires the TeamForge EventQ "EventQ CREATE" permission, project admin, or site admin permissions.
Note: PROJECT_URL_NAME is auto generated by TeamForge with project name initially. This should be found in last path of URL at project home page.

Convention

API requests for viewing and creating tools are constructed as detailed below.
  • List all tools
    • Request Type:
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools
    • Return Format:
      {
        "tools": [
          {
            "id": "unique_tool_id_1",
            "name": "Sample tool name One",
            "service_name": "Sample service name One",
            "project_id": "project id ",
            "active": true,
            "source_ids": [
      
            ]
          },
          {
            "id": "unique_tool_id_2",
            "name": "Sample tool name two",
            "service_name": "Sample service name two",
            "project_id": "project id ",
            "active": true,
            "source_ids": [
              "SourceID1",
              "SourceID2"
            ]
          }
        ]
      }
  • Return Codes
    • Success : 200
    • Error : 404, 503
  • Get one tool
    • Request Type: GET
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID
    • Return Format:
      {
        "tool": {
          "id": "TOOL_ID",
          "name": "Sample tool name two",
          "service_name": "Sample service name two",
          "project_id": "project id ",
          "active": true,
          "source_ids": [
            "SourceID1",
            "SourceID2"
          ]
        }
      }
  • Return Codes
    • Success : 200
    • Error : 404, 503
  • Create a tool
    • Request Type: POST
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools
    • Requires Parameter: PROJECT_URL_NAME
    • Request body:
      {
        "tool": {
          "name": "Sample tool name two",
          "source_ids": [
            "SourceID1",
            "SourceID2"
          ]
        }
      }
  • Return Format:
    {
      "tool": {
        "id": "unique_tool_id_x",
        "name": "Sample tool name two",
        "project_id": "project id ",
        "active": true,
        "source_ids": [
          "SourceID1",
          "SourceID2"
        ]
      },
      "errors": {
        "base": [
          "error msg"
        ],
        "attribute_key": [
          "error msg"
        ]
      }
    }
  • Return Codes
    • Success : 200
    • Error : 404, 503, 422
  • Update a tool
    • Request Type: PUT
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID
    • Requires Parameter: PROJECT_URL_NAME, TOOL_ID
    • Request body:
      {
        "name": "Tool New Name",
        "source_ids": [
          "sourceID3"
        ]
      }
  • Return Format:
    {
      "errors": {
        "base": [
          "error msg"
        ],
        "attribute_key": [
          "error msg"
        ]
      }
    }
  • Return Codes
    • Success : 200
    • Error : 404, 503, 422
  • Activate a tool
    • Request Type: PUT
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID/activate
    • Requires Parameter: PROJECT_URL_NAME, TOOL_ID
    • Return Format:
      {
        "errors": {
          "base": [
            "error msg"
          ],
          "attribute_key": [
            "error msg"
          ]
        }
      }
  • Return Codes
    • Success : 200
    • Error : 404, 503, 422
  • Deactivate a tool
    • Request Type: PUT
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID/deactivate
    • Requires Parameter: PROJECT_URL_NAME, TOOL_ID
    • Return Format:
      {
        "errors": {
          "base": [
            "error msg"
          ],
          "attribute_key": [
            "error msg"
          ]
        }
      }
  • Return Codes
    • Success : 200
    • Error : 404, 503, 422