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