TeamForge EventQ HTTP API for Source CRUD

Overview

  • TeamForge EventQ HTTP API for Sources provides a means to create or view a source. The API supports both data retrieval and submission.
  • Authentication: requires a valid TeamForge SOAP 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 EventQ "EventQ CREATE" permission or TeamForge's project-admin / site-admin permissions.
Note: PROJECT_URL_NAME is auto generated by TeamForge with project name initially. This should be the last value in the URL at project home page.

Convention

API requests for viewing and creating sources are constructed as detailed below.
  • List all sources by Project
    • Request Type: GET
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources
    • Return Format:
      {
        "sources": [
          {
            "id": "5578cd1c0fbb6ad771000001",
            "_type": "Build",
            "tool_id": "552c3736c69d3b3dfb000004",
            "active": true,
            "display_name": "Sample_Build_Source",
            "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
            "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
            "queue_server": "amqp://rabbitmqserver.example.com:5672",
            "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
            "associated_commit_server_id": "551d8560c69d3b474b000102"
          }
        ]
      }
    • Return Codes
      • Success : 200
      • Error : 404, 503
  • List all sources by Tool
    • Request Type: GET
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID/sources
    • Return Format:
      {
        "sources": [
          {
            "id": "5578cd1c0fbb6ad771000001",
            "_type": "Build",
            "tool_id": "552c3736c69d3b3dfb000004",
            "active": true,
            "display_name": "Sample_Build_Source",
            "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
            "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
            "queue_server": "amqp://rabbitmqserver.example.com:5672",
            "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
            "associated_commit_server_id": "551d8560c69d3b474b000102"
          }
        ]
      }
  • Create a source
    • Request Type: POST
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources
    • Request body:

      Required: _type, display_name

      {
        "source": {
          "_type": "Build",
          "tool_id": "552c3736c69d3b3dfb000004",
          "display_name": "Sample_Build_Source",
          "associated_commit_server_id": "551d8560c69d3b474b000102"
        }
      }
    • Return Format:
      {
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "Build",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample_Build_Source",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "associated_commit_server_id": "551d8560c69d3b474b000102"
        },
        "errors": {
          "base": [
            "error msg"
          ],
          "attribute_key": [
            "error msg"
          ]
        }
      }
    • Return Codes
      • Success : 200
      • Error : 404, 503, 422
  • Get one source
    • Request Type: GET
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID
    • Return Format:
      {
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "Build",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample_Build_Source",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "associated_commit_server_id": "551d8560c69d3b474b000102"
        }
      }
    • Return Codes
      • Success : 200
      • Error : 404, 503
  • Update one source
    • Request Type: PUT
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID
    • Request body:
      {
        "tool_id": "552c3736c69d3b3dfb000004",
        "display_name": "Sample_Build_Source",
        "associated_commit_server_id": "551d8560c69d3b474b000102"
      }
    • Return Format:
      {
        "errors": {
          "base": [
            "error msg"
          ],
          "attribute_key": [
            "error msg"
          ]
        }
      }
    • Return Codes
      • Success : 200
      • Error : 404, 503, 422
  • Activate one source
    • Request Type: PUT
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID/activate
    • Return Format:
      {
        "errors": {
          "base": [
            "error msg"
          ],
          "attribute_key": [
            "error msg"
          ]
        }
      }
    • Return Codes
      • Success : 200
      • Error : 404, 503, 422
  • Deactivate one source
    • Request Type: PUT
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID/deactivate
    • Return Format:
      {
        "errors": {
          "base": [
            "error msg"
          ],
          "attribute_key": [
            "error msg"
          ]
        }
      }
    • Return Codes
      • Success : 200
      • Error : 404, 503, 422

Return Types

The source objects have a set of common fields, while some of the fields depend on the _type of the source. The examples below show the type of source and the expected structure of the returned objects.
  • Source Type: Build
    {
            "source": {
              "id": "5578cd1c0fbb6ad771000001",
              "_type": "Build",
              "tool_id": "552c3736c69d3b3dfb000004",
              "active": true,
              "display_name": "Sample_Build_Source",
              "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
              "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
              "queue_server": "amqp://rabbitmqserver.example.com:5672",
              "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
              "associated_commit_server_id": "551d8560c69d3b474b000102"
             }
          }
  • Source Type: Commit
    {
            "source": {
              "id": "5578cd1c0fbb6ad771000001",
              "_type": "Commit",
              "tool_id": "552c3736c69d3b3dfb000004",
              "active": true,
              "display_name": "Sample_ExternalRepository",
              "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
              "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
              "queue_server": "amqp://rabbitmqserver.example.com:5672",
              "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
              "repository_uri": "ssh://sample_gitserver/sample_project"
             }
          }
  • Source Type: CommitCTF
    {
            "source": {
              "id": "5578cd1c0fbb6ad771000001",
              "_type": "CommitCTF",
              "tool_id": "552c3736c69d3b3dfb000004",
              "active": true,
              "ctf_id": "cmmt1234",
              "display_name": "Sample_ExternalRepository",
              "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
              "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
              "queue_server": "amqp://rabbitmqserver.example.com:5672",
              "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
              "repository_uri": "ssh://sample_gitserver/sample_project"
             }
          }
  • Source Type: XDS
    {
            "source": {
              "id": "5578cd1c0fbb6ad771000001",
              "_type": "XDS",
              "tool_id": "552c3736c69d3b3dfb000004",
              "active": true,
              "display_name": "Sample Custom Activity Name One",
              "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
              "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
              "queue_server": "amqp://rabbitmqserver.example.com:5672",
              "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
              "associated_activity_source_id": "55429d045667ba223e000010",
              "activity_source_tag_names": ["Exclusive", "Limited", "Sample"],
              "background_color_value": "#61c0e5",
              "icon_uri": "/sample_icons/custom_source/Sample_Icon_White_12.png"
              "custom_schema_store_id": object.custom_schema_store_id
            }
          }
  • Source Type: Review
    {
            "source": {
              "id": "5578cd1c0fbb6ad771000001",
              "_type": "Review",
              "tool_id": "552c3736c69d3b3dfb000004",
              "active": true,
              "display_name": "Sample Review server Name One",
              "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
              "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
              "queue_server": "amqp://rabbitmqserver.example.com:5672",
              "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
              "commit_association_prefix": "Review"
            }
          }
  • Source Type: WorkItemSource
    {
            "source": {
              "id": "5578cd1c0fbb6ad771000001",
              "_type": "Review",
              "tool_id": "552c3736c69d3b3dfb000004",
              "active": true,
              "display_name": "Sample Work Item Name One",
              "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
              "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
              "queue_server": "amqp://rabbitmqserver.example.com:5672",
              "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
              "associated_commit_server_id": "551d8560c69d3b474b000102"
             }
          }

Validations

The following constitute the validations that are performed for the API request-response parameters.
  • _type
    • type: string
    • present for all sources
    • must be one of: Commit, CommitCTF, WorkItem, CustomActivity, Review, Build, XDS
  • active
    • type: boolean
    • present in all sources
    • must be true or false
    • default value: true
  • associated_activity_source_id
    • type: string
    • attribute in XDS, need not be present
    • references an existing activity source if present
  • commit_association_prefix
    • type: string
    • attribute in Review, must be present
    • must be unique
    • key length must be less than 101
  • activity_source_tag_names
    • type: array with string elements
    • attribute in XDS, need not be present
  • background_color_value
    • type: string
    • attribute of XDS, must be present
    • must be a valid RGB value or a HTML5 color name
  • associated_commit_server_id
    • type: string
    • attribute in Build and WorkItem, need not be present
    • must be associated with a valid commit server if present
  • custom_schema_source_id
    • type: string
    • attribute in XDS, need not be present
    • must be associated to an existing custom_schema_source if present
  • display_type
    • type: string
    • must be present in all sources
    • maximum length less than 101
  • icon_uri
    • type: string
    • attribute of XDS, need not be present
    • has the default value: "/assets/icons/custom_source/PNG_White/CN_Icon_White_12.png"
    • must be a valid uri if present
  • repository_uri
    • type: string
    • must be present in Commit and CommitCTF
    • must be a valid uri if present
    • must be a valid protocol (http, https, ssh, git) if present
  • ctf_id
    • type: string
    • must be present in CommitCTF
    • must be a valid ctf id if present
  • source_association_key
    • type: string in all sources
    • must be present
  • tool_id
    • type: string
    • need not be present or present in any source
    • must be associated with a valid tool if present