Edit this page on GitHub

Home > docs > api > Project

Project

A project is a container for one or more repositories, a secret for accessing the repositories and further configuration.

The REST API provides support for a number of operations:

Create a Project

Creates a new project with specified parameters.

  • URI /api/v1/org/${orgName}/project
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Body
      {
        "name": "myProject",
        "description": "my project",
        
        "repositories": {
          "myRepo": {
            "url": "...",
            "branch": "...",
            "path": "...",
            "secret": "..."
          }
        },
    
        "cfg": {
          ...
        }
      }
    

    All parameters except name are optional.

    The project configuration is a JSON object of the following structure:

      {
        "group1": {
          "subgroup": {
            "key": "value"
          }
        },
        "group2": {
          ...
        }
      }
    

    Most of the parameter groups are defined by used plugins.

  • Success response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "CREATED"
      }
    

**

Update a Project

Updates parameters of an existing project.

  • URI /api/v1/org/${orgName}/project
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Body
      {
        "name": "New name",
        "id": "---",
        "description": "my updated project",
          
        "repositories": {
          "myRepo": {
            "url": "...",
            "branch": "...",
            "secret": "..."
          }
        },
    
        "cfg": {
          ...
        }
      }
    

    All parameters are optional.

    Omitted parameters are not updated.

    Project id is mandatory, in case of updating project name, .

    An empty value must be specified in order to remove a project’s value: e.g. an empty repositories object to remove all repositories from a project.

    See also: project configuration.

  • Success response
      Content-Type: application/json
    

    json { "ok": true, "result": "UPDATED", "id": "---" } **

Delete a Project

Removes a project and its resources.

  • URI /api/v1/org/${orgName}/project/${projectName}
  • Method DELETE
  • Headers Authorization
  • Body none
  • Success response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "DELETED"
      }
    

List Projects

Lists all existing projects.

  • URI /api/v1/org/${orgName}/project
  • Query parameters
    • sortBy: projectId, name;
    • asc: direction of sorting, true - ascending, false - descending
  • Method GET
  • Body none
  • Success response
      Content-Type: application/json
    
      [
        { "name": "..." },
        { "name": "...", "description": "my project", ... }
      ]
    

Get Project Configuration

Returns project’s configuration JSON or its part.

  • URI /api/v1/org/${orgName}/project/${projectName}/cfg/${path}
  • Query parameters
    • path: path to a sub-object in the configuration, can be empty
  • Method GET
  • Headers Authorization
  • Body none
  • Success response
      Content-Type: application/json
    
      {
        ...
      }
    

Update Project Configuration

Updates project’s configuration or its part.

  • URI /api/v1/org/${orgName}/project/${projectName}/cfg/${path}
  • Query parameters
    • path: path to a sub-object in the configuration, can be empty
  • Method PUT
  • Headers Authorization, Content-Type: application/json
  • Body
      Content-Type: application/json
    
      {
        "group1": {
          "param1": 123
        }
      }
    
  • Success response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "UPDATED"
      }
    

List Current Access Rules

Returns project’s current access rules.

  • URI /api/v1/org/${orgName}/project/${projectName}/access
  • Method GET
  • Headers Authorization
  • Body none
  • Success response
      Content-Type: application/json
    
      [
        {"teamId": "...", "level":  "..."},
        ...
      ]
    

Update Access Rules

Updates project’s access rules for a specific team.

  • URI /api/v1/org/${orgName}/project/${projectName}/access
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Body
      Content-Type: application/json
    
      {
        "teamId": "9304748c-81e6-11e9-b909-0fe0967f269a",
        "orgName": "myOrg",
        "teamName": "myTeam",
        "level": "READER"
      }
    

    Either teamId or orgName and teamName combinations are allowed. The level parameter accepts one of the three possible values:

    • READER
    • WRITER
    • OWNER
  • Success response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "UPDATED"
      }
    
  • Example
      curl -ikn -H 'Content-Type: application/json' \
      -d '{"orgName": "MyOrg", "teamName": "myTeam", "level": "READER"}' \
      http://concord.example.com/api/v1/org/MyOrg/project/MyProject/access
    

Bulk Update Access Rules

Updates project’s access rules for multiple teams.

  • URI /api/v1/org/${orgName}/project/${projectName}/access/bulk
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Body
      Content-Type: application/json
    
      [{
        "teamId": "9304748c-81e6-11e9-b909-0fe0967f269a",
        "orgName": "myOrg",
        "teamName": "myTeam",
        "level": "READER"
      }]
    

    Accepts a list of access rule elements. See the non-bulk version of this method for description.

  • Success response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "UPDATED"
      }
    

Move Project to Another Organization

Moves the project to the specified Organization (through Organization name ID)

  • URI /api/v1/org/${orgName}/project
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Body
      Content-Tupe: application/json
    
      {
        "name": "myProject",
        "orgName": "anotherOrg"
      }
    

    Also accepts orgId (Unique Organization ID) instead of orgName in the request body.

  • Success Response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "UPDATED"
      }