Specs: Spec fields

Get spec information

Summary

Get spec file fields.

GET /api/v11/specs/{spec}/ fields

Description

Get fields for a spec type.

Parameter Description Type Parameter Type Required

spec

Spec type. Valid spec types and location in the Helix Server spec depot:

  • branch: //spec/branch/
  • change: the change spec is not stored in the Helix Server spec depot
  • client: //spec/client/
  • depot: //spec/depot/
  • group: //spec/group/
  • job: //spec/job/
  • label: //spec/label/
  • license: //spec/license.p4s
  • protect: //spec/protect.p4s
  • spec: //spec/spec/
  • stream: //spec/stream/
  • triggers: //spec/triggers.p4s
  • typemap: //spec/typemap.p4s
  • user: //spec/user/

string

path

Yes

fields

Omitting the fields parameter or including the fields parameter with no fields specified, returns all of the fields in the spec including any custom fields.

Limit the response to specific fields by including a list of comma-separated fields in the request. The fields available depend on the spec type requested. Invalid fields do not cause an error and are ignored.

array of strings path No

Example usage

Fetch all fields for the job spec

Fetching all fields for the job spec

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/job/fields"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "job": {
      "Job": {
        "code": "101",
        "dataType": "word",
        "displayLength": "32",
        "fieldType": "required"
      },
      "Status": {
        "code": "102",
        "dataType": "select",
        "displayLength": "10",
        "fieldType": "required",
        "options": [
          "open",
          "suspended",
          "fixed",
          "closed"
        ],
        "default": "open"
      },
      "Created_by": {
        "code": "103",
        "dataType": "word",
        "displayLength": "32",
        "fieldType": "once",
        "default": "$user"
      },
      "Description": {
        "code": "105",
        "dataType": "text",
        "displayLength": "0",
        "fieldType": "required",
        "default": "$blank"
      },
      "Date_modified": {
        "code": "130",
        "dataType": "date",
        "displayLength": "20",
        "fieldType": "always",
        "default": "$now"
      }
    }
  }
}

Limit results to job and status fields for the job spec

Limit the results to the job and status fields for the job spec.

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/job/fields?fields=status,job"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "job": {
      "Job": {
        "code": "101",
        "dataType": "word",
        "displayLength": "32",
        "fieldType": "required"
      },
      "Status": {
        "code": "102",
        "dataType": "select",
        "displayLength": "10",
        "fieldType": "required",
        "options": [
          "open",
          "suspended",
          "fixed",
          "closed"
        ],
        "default": "open"
      }
    }
  }
}

Limit results to depot and type fields for the depot spec

Limit the results to the depot and type fields for the depot spec.

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/depot/fields?fields=depot,type"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "depot": {
      "Depot": {
        "code": "251",
        "dataType": "word",
        "displayLength": "32",
        "fieldType": "key"
      },
      "Type": {
        "code": "255",
        "dataType": "word",
        "displayLength": "10",
        "fieldType": "required"
      }
    }
  }
}

Limit results to status and type fields for the change spec

Limit the results to the status and type fields for the change spec.

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/change/fields?fields=status,type"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "change": {
      "Status": {
        "code": "205",
        "dataType": "word",
        "displayLength": "10",
        "fieldType": "always",
        "order": "5",
        "position": "R"
      },
      "Type": {
        "code": "211",
        "dataType": "select",
        "displayLength": "10",
        "fieldType": "optional",
        "order": "6",
        "position": "L",
        "options": [
          "public",
          "restricted"
        ]
      }
    }
  }
}

If a request fails

<error code>:

  • 400 Unknown spec type requested
  • 401 Insufficient permissions to fetch spec fields
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
}