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 |
---|---|---|---|---|
|
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 |
|
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 |
---|---|---|---|---|
|
Project ID |
string |
path |
Yes |
|
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 |
---|---|---|---|---|
|
Project Name (is also used to generate the Project ID) |
string |
form |
Yes |
|
An array of project members. |
array |
form |
Yes |
|
An optional array of project subgroups. |
array |
form |
No |
|
An optional array of project owners. |
array |
form |
No |
|
An optional project description. |
string |
form |
No |
|
Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false) |
boolean |
form |
No |
|
Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"} |
array |
form |
No |
|
Configuration for testing/continuous integration. |
array |
form |
No |
|
Optional branch definitions for this project. |
array |
form |
No |
|
An optional jobview for associating certain jobs with this project. |
string |
form |
No |
|
Email members, moderators and followers when a change is committed. |
boolean |
form |
No |
|
Email members and moderators when a new review is requested. |
boolean |
form |
No |
|
An optional array of defaults at a project level (for example default reviewers). |
array |
form |
No |
|
An optional to retain the default reviewers. |
boolean |
form |
No |
|
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.
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 |
---|---|---|---|---|
|
Project ID |
string |
path |
Yes |
|
Project Name (changing the project name does not change the project ID) |
string |
form |
No |
|
An array of project members. |
array |
form |
No |
|
An optional array of project subgroups. |
array |
form |
No |
|
An optional array of project owners. |
array |
form |
No |
|
Your project description. |
string |
form |
No |
|
Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false) |
boolean |
form |
No |
|
Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"} |
array |
form |
No |
|
Configuration for testing/continuous integration. |
array |
form |
No |
|
Optional branch definitions for this project. |
array |
form |
No |
|
A jobview for associating certain jobs with this project. |
string |
form |
No |
|
Email members, moderators and followers when a change is committed. |
boolean |
form |
No |
|
Email members and moderators when a new review is requested. |
boolean |
form |
No |
|
An optional array of defaults at a project level (for example default reviewers). |
array |
form |
No |
|
An optional to retain the default reviewers. |
boolean |
form |
No |
|
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:
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.
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.
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 |
---|---|---|---|---|
|
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"
}
Your search for returned result(s).