Projects

Get all projects

This endpoint retrieves a list of project resources.

GET /api/v2/projects/

Query Parameters

The following parameters may be used to filter the project resources in the response. Use in conjunction with Custom Filtering Lookups for greater utility.

Parameter Description
application Filter projects by Application ID.
name Filter projects by name.
slug Filter projects by slug.
ordering Sort projects by the specified field. Prefix field name with minus to sort descending. Sortable fields: name, created, updated.
search Filter projects by performing a textual search on name and profile name.
components Filter projects by component IDs.
creator Filter projects by user ID.
created Filter projects by the date they were created. See Custom Filtering Lookups.
updated Filter projects by date were updated. See Custom Filtering Lookups.
custom_attributes Filter projects by their custom attributes.
GET /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": 1280,
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png",
            "active": true
        },
        "profile_draft": null,
        "archived": false,
        "name": "Project Test",
        "creator": 1,
        "description": "API Project",
        "tags": ["foo", "bar"],
        "application_tags": ["baz", "qux"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": {
            "id": 8,
            "slug": "parent-984-gamma",
            "name": "Parent 9.8.4 Gamma",
            "url": "http://example.com/bunits/bu-test/app-test/parent-984-gamma/",
            "archived": false
        },
        "base_project": {
            "id": 10,
            "name": "base 9.8.4 Gamma",
            "slug": "base-984-gamma",
            "url": "http://example.com/bunits/bu-test/app-test/base-984-gamma/",
            "archived": false
        },
        "components": ["CSC7"],
        "connected_component": null,
        "users": [{
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "is_creator": true
        }],
        "groups": [{
            "id": "G1",
            "name": "Devs",
            "role": "PR4"
        }],
        "custom_attributes": {
          "slug": "value"
        },
        "survey_complete": true,
        "survey_dirty": false,
        "locked_on": null,
        "locked_by": null,
        "locked": false,
        "release_project": true,
        "risk_policy_compliant": true,
        "risk_policy": 1,
        "project_classification": 1,
        "project_locked": false,
        "project_lock_modified_on": null,
        "project_lock_modified_by": null
    }]
}

Include Parameters

See the Include Parameters section for more details.

Parameter Description
permissions Includes a list of permissions the requesting user has for the project.
task_counts Includes counts of Countermeasures broken down by phase and completeness for the project. See note below.
incomplete_tasks Includes a count of incomplete Countermeasures broken down by high (7-10), medium (4-6), and low (1-3) priorities.
task_metrics Includes metrics associated with Countermeasures.
problem_metrics Includes metrics associated with Weaknesses.

Note: The "total" count represents the total number of applicable Countermeasures (those not marked N/A), and "complete" marks the number of Countermeasures whose status meaning is Done.

GET /api/v2/projects/1/?include=permissions,task_counts,incomplete_tasks HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": 1280,
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png",
            "active": true
        },
        "profile_draft": null,
        "archived": false,
        "name": "Project Test",
        "creator": 1,
        "description": "API Project",
        "tags": ["foo", "bar"],
        "application_tags": ["baz", "qux"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": null,
        "base_project": null,
        "components": [],
        "connected_component": null,
        "users": [{
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "is_creator": true
        }],
        "groups": [{
            "id": "G1",
            "name": "Devs",
            "role": "PR4"
        }],
        "custom_attributes": {
          "slug": "value"
        },
        "permissions": [
            "edit_project_details",
            "assign_task",
            "mark_task",
            "create_project_specific_task",
            "archive_project",
            "verify_task",
            "edit_project_membership",
            "view_project",
            "write_task_note",
            "sync_with_issue_tracker",
            "edit_project_survey"
        ],
        "incomplete_tasks": {
            "high": 38,
            "medium": 60,
            "low": 11
        },
        "task_counts": {
            "Requirements": {
                "total": 28,
                "na": 3,
                "complete": 4,
                "slug": "requirements"
            },
            "Architecture & Design": {
                "total": 6,
                "na": 3,
                "complete": 1,
                "slug": "architecture-design"
            },
            "Development": {
                "total": 30,
                "na": 3,
                "complete": 5,
                "slug": "development"
            },
            "Testing": {
                "total": 57,
                "na": 3,
                "complete": 2,
                "slug": "testing"
            }
        },
        "survey_complete": true,
        "survey_dirty": false,
        "locked_on": null,
        "locked_by": null,
        "locked": false,
        "release_project": false,
        "risk_policy_compliant": true,
        "risk_policy": 1,
        "project_classification": 1,
        "project_locked": false,
        "project_lock_modified_on": null,
        "project_lock_modified_by": null
    }]
}

Exclude Parameters

See the Exclude Parameters section for more details.

Parameter Description
members Excludes the list of users and groups in a project.
GET /api/v2/projects/1/?exclude=members HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": 1280,
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png",
            "active": true
        },
        "profile_draft": null,
        "archived": false,
        "name": "Project Test",
        "creator": 1,
        "description": "API Project",
        "tags": ["foo", "bar"],
        "application_tags": ["baz", "qux"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": null,
        "base_project": null,
        "components": [
                { 
                    "id": "CSC7",
                    "title": "My Component"
                },
                {
                    "id": "CSC8",
                    "title": "My Component2"
                }
            ],
        "connected_component": null,
        "custom_attributes": {
          "slug": "value"
        },
        "survey_complete": true,
        "survey_dirty": false,
        "locked_on": null,
        "locked_by": null,
        "locked": false,
        "release_project": false,
        "risk_policy_compliant": true,
        "risk_policy": 1,
        "project_classification": 1,
        "project_locked": false,
        "project_lock_modified_on": null,
        "project_lock_modified_by": null
    }]
}

Expand Parameters

See the Expand Parameters section for more details.

Parameter Description
application The application field is expanded to display information about the project's application.
creator The creator field is expanded to display information about the project creator.
risk_policy The Risk Policy field is expanded to display information about the associated Risk Policy.
project_classification The Project Classification field is expanded to display information about the associated project classification.
GET /api/v2/projects/?expand=application,creator,risk_policy HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": {
          "id": 1280,
          "name": "Application Test",
          "slug": "application-test"
        },
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png",
            "active": true
        },
        "profile_draft": null,
        "archived": false,
        "name": "Project Test",
        "creator": {
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true
        },
        "description": "API Project",
        "tags": ["foo", "bar"],
        "application_tags": ["baz", "qux"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": null,
        "base_project": null,
        "components": [],
        "connected_component": null,
        "users": [{
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true
        }],
        "groups": [{
            "id": "G1",
            "name": "Devs",
            "role": "PR4"
        }],
        "custom_attributes": {
          "slug": "value"
        },
        "survey_complete": true,
        "survey_dirty": false,
        "locked_on": null,
        "locked_by": null,
        "locked": false,
        "release_project": false,
        "risk_policy_compliant": true,
        "risk_policy": {
            "id": 1,
            "name": "All Risk",
            "description": "Applies to all applications",
            "filters": {
                "phases": ["requirements", "architecture-design", "development", "testing"],
                "priority": 7,
                "tags": ["tag1", "tag2"]
            },
            "conditions": {
                "task_statuses": ["TS1"]
            },
            "is_org_default": true,
            "created": "2018-01-31T17:30:26.175423-05:00",
            "last_updated": "2018-01-31T17:30:26.175253-05:00"
        },
        "project_classification": {
            "id": 1,
            "ordinal": 1,
            "name": "Maximum",
            "description": "Used for projects with maximum risk.",
            "default_risk_policy": 1,
            "risk_policies": [1],
            "answers": ["A168"],
            "last_update_date_time": "2019-05-28T11:34:21.908541-04:00",
            "is_unclassified": false
        },
        "project_locked": false,
        "project_lock_modified_on": null,
        "project_lock_modified_by": null
    }]
}

Get a specific project

This endpoint retrieves a specific project resource, as specified by the id parameter.

GET /api/v2/projects/{project_id}/

URL Parameters

Parameter Description
project_id The id of the project to retrieve.
GET /api/v2/projects/1936/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1936,
    "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
    "slug": "project-test",
    "url": "http://example.com/bunits/bu-test/app-test/project-test",
    "application": 1280,
    "profile" : {
        "id": "P9",
        "name": "Android App",
        "logo_url": "/static/images/android.png"
    },
    "profile_draft": null,
    "archived": false,
    "name": "Project Test",
    "creator": 1,
    "description": "API Project",
    "tags": ["foo", "bar"],
    "application_tags": ["baz", "qux"],
    "created": "2015-04-15T19:30:04.132712Z",
    "updated": "2015-04-15T19:57:15.042353Z",
    "parent": null,
    "base_project": null,
    "components": [
                { 
                    "id": "CSC7",
                    "title": "My Component"
                },
                {
                    "id": "CSC8",
                    "title": "My Component2"
                }
            ],
    "connected_component": null,
    "users": [{
        "id": "1",
        "email": "test@example.com",
        "role": "PR4",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true,
        "is_creator": true
    }],
    "groups": [{
        "id": "G1",
        "name": "Devs",
        "role": "PR4"
    }],
    "custom_attributes": {
      "slug": "value"
    },
    "survey_complete": true,
    "survey_dirty": false,
    "locked_on": null,
    "locked_by": null,
    "locked": false,
    "release_project": false,
    "risk_policy_compliant": true,
    "risk_policy": 1,
    "project_classification": 1,
    "project_locked": false,
    "project_lock_modified_on": null,
    "project_lock_modified_by": null
}

Create a new project

Fields Required Description
application Yes The ID of the application the project should be created under.
groups No A list of dictionaries per group that are to be assigned to the project. Each dictionary should contain the group's id and desired role.
Note: If this parameter is included, the Business Unit that the application will add the new project to must either have these groups as members or be configured with the "All Users" option.
name Yes The name of the new project.
profile No The ID of the desired profile for the project.
users No A list of dictionaries per user that are to be assigned to the project. Each dictionary should contain the user's email and desired role.
locked No A boolean field to lock or unlock the project. It can only be used by users that have the lock_project_survey permission.
risk_policy No The ID of the Risk Policy that applies to this project.
tags No A list of tags applicable to the project.
answers No An array of Answer IDs that represent survey answers that apply to this project. Answer IDs are strings and deployment-specific.
Note: For each project, SD Elements selects Answers first from the Survey profile and then from the Answers that users provide while manually completing the Survey.
custom_attributes Depends The JSON of custom attributes as defined by your administrator. This field is not required unless mandated by your administrator. See Project attributes for more information.
Note: The custom_attributes field is case-sensitive. Fields included with a project payload that have not been added through the web front-end are saved but only accessible via the API.
POST /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "application": 1280,
    "name": "Project Test",
    "profile": "P9",
    "answers": ["A1", "A2"],
    "users": [{"email": "test@example.com", "role": "PR4"}],
    "groups": [{"id": "G1", "role": "PR4"}]
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1936,
    "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
    "slug": "project-test",
    "url": "http://example.com/bunits/bu-test/app-test/project-test",
    "application": 1280,
    "profile" : {
        "id": "P9",
        "name": "Android App",
        "logo_url": "/static/images/android.png"
    },
    "profile_draft": null,
    "archived": false,
    "name": "Project Test",
    "creator": 1,
    "description": "API Project",
    "tags": [],
    "application_tags": [],
    "created": "2015-04-15T19:30:04.132712Z",
    "updated": "2015-04-15T19:57:15.042353Z",
    "parent": null,
    "base_project": null,
    "users": [{
        "id": "1",
        "email": "test@example.com",
        "role": "PR4",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true,
        "is_creator": true
    }],
    "groups": [{
        "id": "G1",
        "name": "Devs",
        "role": "PR4"
    }],
    "custom_attributes": {
    },
    "survey_complete": true,
    "survey_dirty": false,
    "locked_on": null,
    "locked_by": null,
    "locked": false,
    "risk_policy_compliant": true,
    "risk_policy": 1,
    "project_classification": null,
    "project_locked": false,
    "project_lock_modified_on": null,
    "project_lock_modified_by": null
}

Update a project

Update a single project by specifying a new name and a new application. The project to update is identified by the id.

PATCH /api/v2/projects/{project_id}/

URL Parameters

Parameter Description
project_id The id of the project to update

Payload

Fields Required Description
project_locked No A boolean field to lock or unlock the project. It can only be used by users that have the lock_project permission. Note: The project_locked field can only be edited if the ENABLE_PROJECT_LOCKING flag is enabled.
locked No A boolean field to lock or unlock the project survey. It can only be used by users that have the lock_project_survey permission. Note: This field is deprecated and will be changed to survey_locked in future releases.
application No The ID of the application the project should be created under.
profile No The ID of the desired profile for the project.
archived No A boolean to archive and unarchive a project.
name No The name of the project.
description No The description of the project.
tags No The list of project tags.
parent No The ID, name, slug, and URL of the parent project.
base_project No The ID, name, slug, and URL of the original project.
users No A list of dictionaries per user that are to be assigned to the project. Each dictionary should contain the user's email and desired role.
groups No A list of dictionaries per group that are to be assigned to the project. Each dictionary should contain the group's ID and desired role.
risk_policy No The ID of the Risk Policy that applies to this project.
custom_attributes Depends The JSON of custom attributes as defined by your administrator. This field is not required unless mandated by your administrator. See Project attributes for more information. Note: The custom_attributes field is case-sensitive. Fields included with a project payload that have not been added through the web front-end are saved but only accessible via the API.
PATCH /api/v2/projects/1936/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "application": 1,
    "name": "This is the project's new name!"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1936,
    "external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
    "slug": "project-test",
    "url": "http://example.com/bunits/bu-test/app-test/project-test",
    "application": 1,
    "profile" : {
        "id": "P9",
        "name": "Android App",
        "logo_url": "/static/images/android.png"
    },
    "profile_draft": null,
    "archived": false,
    "name": "This is the project's new name!",
    "creator": 1,
    "description": "API Project",
    "tags": ["foo", "bar"],
    "application_tags": ["baz", "qux"],
    "created": "2015-04-15T19:30:04.132712Z",
    "updated": "2015-07-23T15:52:14.482992Z",
    "parent": null,
    "base_project": null,
    "components": [
                { 
                    "id": "CSC7",
                    "title": "My Component"
                },
                {
                    "id": "CSC8",
                    "title": "My Component2"
                }
            ],
    "users": [{
        "id": "1",
        "email": "test@example.com",
        "role": "PR4",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true,
        "is_creator": true
    }],
    "groups": [{
        "id": "G1",
        "name": "Devs",
        "role": "PR4"
    }],
    "custom_attributes": {
      "slug": "value"
    },
    "survey_complete": true,
    "survey_dirty": false,
    "locked_on": "2016-06-01T14:39:45.083334Z",
    "locked_by": 1,
    "locked": true,
    "risk_policy_compliant": true,
    "risk_policy": 1,
    "project_classification": 1
}

Delete a project

This endpoint deletes a specific project, specified by the project id.

DELETE /api/v2/projects/{project_id}/

URL Parameters

Parameter Description
project_id The id of the Project to delete.
DELETE /api/v2/projects/10/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

results matching ""

    No results matching ""