Helix Swarm Guide (2019.1)

Projects : Swarm Projects

Get List of Projects

Summary

Get List of Projects

GET /api/v9/projects/

Description

Returns a list of projects in Swarm that are visible to the current user. Administrators will see all projects, including private ones.

Parameters

Parameter Description Type Parameter Type Required

fields

An optional comma-separated list (or array) of fields to show for each project. Omitting this parameter or passing an empty value shows all fields.

string

query

No

workflow

An optional parameter to only list projects using a workflow.

string

query

No

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "projects": [
    {
      "id": "testproject3",
      "branches": [
        {
          "id": "main",
          "name": "main",
          "paths": ["//depot/main/TestProject/..."],
          "moderators": [],
          "moderators-groups": []
        }
      ],
      "deleted": false,
      "description": "Test test test",
      "followers": [],
      "jobview": "subsystem=testproject",
      "members": ["alice"],
      "name": "TestProject",
      "owners": [],
      "private": false,
      "subgroups": []
    }
  ]
}

Examnple usage

Listing projects

To list all projects:

curl -u "username:password" "https://my-swarm-host/api/v9/projects?fields=id,description,members,name"

Pagination is not currently supported by this endpoint. Swarm responds with a list of all projects:

{
  "projects": [
    {
      "id": "testproject1",
      "description": "Test test test",
      "members": ["alice"],
      "name": "TestProject"
    },
    {
      "id": "testproject2",
      "description": "Test test test",
      "members": ["alice"],
      "name": "TestProject"
    }
  ]
}

Project administrators wishing to see the tests and deploy fields must fetch projects individually.

Get Project Information

Summary

Get Project Information

GET /api/v9/projects/{id}

Description

Retrieve information about a project.

Parameters

Parameter Description Type Parameter Type Required

id

Project ID

string

path

Yes

fields

An optional comma-separated list (or array) of fields to show for each project. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject4",
    "defaults": [],
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": [],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "description": "Test test test",
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": []
  }
}

Example usage

Fetching a project

To fetch an individual project:

curl -u "username:password" \
     "https://my-swarm-host/api/v9/projects/testproject2?fields=id,description,members,name"

Swarm responds with a project entity:

{
  "project": {
    "id": "testproject2",
    "defaults": [],
    "description": "Test test test",
    "members": ["alice"],
    "name": "TestProject 2"
  }
}

Project administrators have access to additional fields (tests and deploy) when fetching individual projects using this endpoint.

Create a new Project

Summary

Create a new Project

POST /api/v9/projects/

Description

Creates a new project in Swarm.

Parameters

Parameter Description Type Parameter Type Required

name

Project Name (is also used to generate the Project ID)

string

form

Yes

members

An array of project members.

array

form

Yes

subgroups

An optional array of project subgroups.

array

form

No

owners

An optional array of project owners.

array

form

No

description

An optional project description.

string

form

No

private

Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false)

boolean

form

No

deploy

Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"}

array

form

No

tests

Configuration for testing/continuous integration.

array

form

No

branches

Optional branch definitions for this project.

array

form

No

jobview

An optional jobview for associating certain jobs with this project.

string

form

No

emailFlags[change_email_project_users]

Email members, moderators and followers when a change is committed.

boolean

form

No

emailFlags[review_email_project_members]

Email members and moderators when a new review is requested.

boolean

form

No

defaults

An optional array of defaults at a project level (for example default reviewers).

array

form

No

retainDefaultReviewers

An optional to retain the default reviewers.

boolean

form

No

minimumUpVotes

An optional to set the minimum number of up votes required.

string

form

No

Examples responses

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject5",
    "defaults": [],
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": [],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "Test test test",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject6",
    "defaults": {"user2":{"required":true}},
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": {
             "reviewers":{
                 "groups":{"swarm-group-group1":{"required":"1"}},
                 "users":{"user1":{"required":true}}
             }
        },
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Example usage

Creating a new project

To create a project:

curl -u "username:password" \
     -d "name=TestProject 3" \
     -d "description=The third iteration of our test project." \
     -d "members[]=alice" \
     -d "members[]=bob" \
     "https://my-swarm-host/api/v9/projects/"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject3",
    "defaults": [],
    "branches": [],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "The third iteration of our test project.",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice", "bob"],
    "name": "TestProject 3",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Creating a private project with branches

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch - an example of this accompanies the PATCH endpoint documentation.

Projects are public by default. Marking a project as Private requires using {private: true} in JSON, and using -d "private=1" in regular form-encoded requests.

Important

Form-encoded requests only accept 0 for false in boolean values — using the word false will be evaluated as a non-zero (and therefore non-false) value.

curl -u "username:password" \
     -d "name=TestProject 4" \
     -d "private=1" \
     -d "members[]=bob" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     "https://my-swarm-host/api/v9/projects"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject-4",
    "defaults": [],
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": [],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": true,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Creating a project to add default reviewers (

curl -u "<user>:<password>" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '"name": "testproject-4", \
         "members": ["bob"], \
         "defaults":{"reviewers":{"user2":{"required":true}} \
         "branches":[{ \
           "name":"Branch One", \
           "paths":{"//depot/main/TestProject/..."} \
           "defaults":{"reviewers":{"swarm-group-group1":{"required":"1"},"user1":{"required":true}}]' \
     "https://my-swarm-host/api/v9/projects/testproject-4"

Or without JSON content:

curl -u "username:password" \
     -X PATCH \
     -d "name=TestProject 4" \
     -d "members[]=bob" \
     -d "defaults[reviewers][user2][required]=true" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[0][defaults][reviewers][swarm-group-group1][required]=1" \
     -d "branches[0][defaults][reviewers][user1][required]=true" \
     "https://my-swarm-host/api/v9/projects/testproject-4"

Swarm responds with project entity similar to:

{
  "project": {
    "id": "testproject-4",
    "defaults": ["user2":["required":true]]],
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": ["reviewers":["swarm-group-group1":["required":"1"], "user1":["required":true]]],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Edit a Project

Summary

Edit a Project

PATCH /api/v9/projects/{id}

Description

Change the settings of a project in Swarm. If a project has owners set, only the owners can perform this action.

Parameters

Parameter Description Type Parameter Type Required

id

Project ID

string

path

Yes

name

Project Name (changing the project name does not change the project ID)

string

form

No

members

An array of project members.

array

form

No

subgroups

An optional array of project subgroups.

array

form

No

owners

An optional array of project owners.

array

form

No

description

Your project description.

string

form

No

private

Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false)

boolean

form

No

deploy

Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"}

array

form

No

tests

Configuration for testing/continuous integration.

array

form

No

branches

Optional branch definitions for this project.

array

form

No

jobview

A jobview for associating certain jobs with this project.

string

form

No

emailFlags[change_email_project_users]

Email members, moderators and followers when a change is committed.

boolean

form

No

emailFlags[review_email_project_members]

Email members and moderators when a new review is requested.

boolean

form

No

defaults

An optional array of defaults at a project level (for example default reviewers).

array

form

No

retainDefaultReviewers

An optional to retain the default reviewers.

boolean

form

No

minimumUpVotes

An optional to set the minimum number of up votes required.

string

form

No

Example responses

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject7",
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject8",
    "defaults": {"user2":{"required":true}},
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": {
             "reviewers":{
                 "groups":{"swarm-group-group1":{"required":"1"}},
                 "users":{"user1":{"required":true}}
             }
         },
         "minimumUpVotes": null,
         "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Example usage

Editing a project

To edit a project:

Note

It is safe to edit a project without specifying branches, but the instructions for adding branches contain important information for modifying branch configuration.

curl -u "username:password" \
     -X PATCH
     -d "description=Witness the power of a fully operational Swarm project." \
     "https://my-swarm-host/api/v9/projects/testproject3"

Swarm responds with the updated project entity:

{
  "project": {
    "id": "testproject3",
    "branches": [],
    "defaults": [],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "Witness the power of a fully operational Swarm project.",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject 3",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Editing a project to add a moderated branch and make the project public

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch.

Important

If you have existing branches, you must specify all of them in the query to avoid data loss. This operation sets the value of the entire branches property to match the provided input.

Marking a private project as Public requires using {private: false} in JSON, or using -d "private=0" in regular form-encoded requests.

Important

Form-encoded requests only accept 0 for false in boolean values — using the word false will be evaluated as a non-zero (and therefore non-false) value.

curl -u "username:password" \
     -X PATCH \
     -d "private=0" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[1][name]=Branch Two" \
     -d "branches[1][paths][]=//depot/main/SecondBranch/..." \
     -d "branches[1][moderators][]=bob" \
     -d "branches[1][moderators-groups][]=group1" \
     "https://my-swarm-host/api/v9/projects/testproject-4"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject-4",
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": [],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      },
      {
        "paths": [
          "//depot/main/SecondBranch/..."
        ],
        "name": "Branch Two",
        "id": "branch-two",
        "moderators": ["bob"],
        "moderators-groups": ["group1"],
        "defaults": [],
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Editing a project to add default reviewers

curl -u "<user>:<password>" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '"defaults":{"reviewers":{"user2":{"required":true}} \
         "branches":[{ \
           "name":"Branch One", \
           "paths":{"//depot/main/TestProject/..."} \
           "defaults": { \
               "reviewers":{ \
                   "groups":{"group1":{"required":"1"}}, \
                   "users":{"user1":{"required":true}} \
               } \
           }]' \
     "https://my-swarm-host/api/v9/projects/testproject-4"

Or without JSON content:

curl -u "username:password" \
     -X PATCH \
     -d "name=TestProject 4" \
     -d "members[]=bob" \
     -d "defaults[reviewers][user2][required]=true" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[0][defaults][reviewers][groups][group1][required]=1" \
     -d "branches[0][defaults][reviewers][users][user1][required]=true" \
     "https://my-swarm-host/api/v9/projects/testproject-4"

Swarm responds with project entity similar to:

{
  "project": {
    "id": "testproject-4",
    "defaults": ["user2":["required":true]]],
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": {
               "reviewers":{
                   "groups":{"group1":{"required":"1"}},
                   "users":{"user1":{"required":true}}
               }
           },
        "minimumUpVotes": null,
        "retainDefaultReviewers": false
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "minimumUpVotes": null,
    "retainDefaultReviewers": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Delete a Project

Summary

Delete a Project

DELETE /api/v9/projects/{id}

Description

Mark a Swarm project as deleted. The project ID and name cannot be reused. If a project has owners set, only the owners can perform this action.

Parameters

Parameter Description Type Parameter Type Required

id

Project ID

string

path

Yes

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "id": "testproject"
}

Example usage

Deleting a project:

Super users, administrators, and owners can delete projects. Members can delete projects that have no owners set.

curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/projects/testproject3"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted project:

{
  "id": "testproject3"
}