Versions Compared

Old Version 1

changes.mady.by.user Russ Frisch

Saved on

compared with

New Version 2

changes.mady.by.user Russ Frisch

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Introduction

This API provides functionalities to manage people, projects, organizational hierarchy, and their relationships. Providing this data via these APIs can be useful for providing filters for Insights dashboards. You can create, read, and list data for each resource, allowing you to efficiently manage projects, teams, and their relationships. Feel free to explore each endpoint section for further details.

Remember to authenticate before accessing any of these endpoints.

People

The People endpoint manages data about the users involved in your projects. Use these functions to create new people records, retrieve all people records, or access specific person details.

URL

METHOD

DESCRIPTION

Scope

REQUEST

RESPONSE

/api/v2/data/people

POST

Creates a new record representing a user that is associated with any projects.

Note
Required Fields: email
externalId: Id for relating this person back to the original data source.
organization/business/department/group/team: Use these fields for associating organizational hierarchy metadata.
organization would represent the highest entities while team would represent the lowest level.

API Access

Code Block
languagejson
{
  "firstName": "John",
  "lastName": "Doe",
  "displayName": "John Doe",
  "email": "jd@opsera.io",
  "externalId": "25ce97e1-549b-4f31-bd01-80490847f8a6",
  "organization": "Opsera",
  "business_group": "Engineering",
  "applicationdepartment": "Platform",
  "projectgroup": "Phase 2",
  "team": "AOD"
}
Code Block
200 OK

/api/v2/data/people

GET

Lists all people records for which you have access.

API Access

Code Block
languagejson
{
  "count": 1,
  "data": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "displayName": "John Doe",
      "email": "jd@opsera.io",
      "externalId": "25ce97e1-549b-4f31-bd01-80490847f8a6",
      "organization": "Opsera",
      "business_group": "Engineering",
      "applicationdepartment": "Platform",
      "projectgroup": "Phase 2",
      "team": "AOD"
    },
  ]
}

/api/v2/data/people/{email}

GET

Gets the people record associated with the given email address.

API Access

Code Block
languagejson
{
  "firstName": "John",
  "lastName": "Doe",
  "displayName": "John Doe",
  "email": "jd@opsera.io",
  "externalId": "25ce97e1-549b-4f31-bd01-80490847f8a6",
  "organization": "Opsera",
  "business_group": "Engineering",
  "applicationdepartment": "Platform",
  "projectgroup": "Phase 2",
  "team": "AOD"
}

Projects

The Project endpoint manages data about the relevant projects. Use these functions to create new project records, retrieve all project records, or access specific project details.

URL

METHOD

DESCRIPTION

Scope

REQUEST

RESPONSE

/api/v2/data/project

POST

Creates a new record representing a project that is associated with any users.

Note
Required Fields: projected, projectName
externalId: Id for relating this person back to the original data source.
organization/business/department/group/team: Use these fields for associating organizational hierarchy metadata.
organization would represent the highest entities while team would represent the lowest level.
assets: A project can represent 1 or more repositories and/or services

API Access

Code Block
languagejson
{
  "projectId": "2322345",
  "projectName": "Phase 2",
  "projectOwner": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "jd@opsera.io"
  }
  "externalId": "25ce97e1-549b-4f31-bd01-80490847f8a6",
  "organization": "Opsera",
  "business": "Engineering",
  "department": "Platform",
  "group": "Phase 2",
  "team": "AOD"
  "assets": [
    "repositories": [{
      name: "web-portal",
      platform: "github.com",
      url: "https://github.com/Opsera/web-portal.git",
    }],
    "services": [{
      name: "ha-proxy",
      identifier: "haprox01",
      dependencies: {},
      externalId: "b558c4d4-1eba-45e8-92bb-b255df6abd87",
    }]
  ]
}
Code Block
200 OK

/api/v2/data/projects

GET

Lists all project records for which you have access.

API Access

Code Block
languagejson
{
  "count": 1,
  "data": [{
      "projectId": "2322345",
      "projectName": "Phase 2",
      "projectOwner": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "jd@opsera.io"
      }
      "externalId": "25ce97e1-549b-4f31-bd01-80490847f8a6",
      "organization": "Opsera",
      "business": "Engineering",
      "department": "Platform",
      "group": "Phase 2",
      "team": "AOD"
      "assets": [
        "repositories": [{
          name: "web-portal",
          platform: "github.com",
          url: "https://github.com/Opsera/web-portal.git",
        }],
        "services": [{
          name: "ha-proxy",
          identifier: "haprox01",
          dependencies: {},
          externalId: "b558c4d4-1eba-45e8-92bb-b255df6abd87",
        }]
      ]
  }]
}

/api/v2/data/project/{projectId}

GET

Gets the project record associated with the given email address.

API Access

Code Block
languagejson
{
  "projectId": "2322345",
  "projectName": "Phase 2",
  "projectOwner": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "jd@opsera.io"
  }
  "externalId": "25ce97e1-549b-4f31-bd01-80490847f8a6",
  "organization": "Opsera",
  "business": "Engineering",
  "department": "Platform",
  "group": "Phase 2",
  "team": "AOD"
  "assets": [
    "repositories": [{
      name: "web-portal",
      platform: "github.com",
      url: "https://github.com/Opsera/web-portal.git",
    }],
    "services": [{
      name: "ha-proxy",
      identifier: "haprox01",
      dependencies: {},
      externalId: "b558c4d4-1eba-45e8-92bb-b255df6abd87",
    }]
  ]
}

...

People / Project Relationship Mapping

The Mappings endpoint bridges the gap between people and projects. Use these functions to assign individuals to projects and retrieve information about existing assignments.

URL

METHOD

DESCRIPTION

Scope

REQUEST

RESPONSE

/api/v2/data/mapping

POST

Creates a mapping record representing the relationship between the project and people.

Note
Required Fields: attribute1, attribute2. Representing either the project or person which will be associated to either a project or person.
mappingType: Identifies the type of mapping.
Supported types: "project-people", "parent-child"
relationship: Identifies the type of relationship.
Supported types: "many-to-many", "many-to-one", "one-to-one", "one-to-many"

API Access

Code Block
languagejson
{
  "attribute1": "John2322345", // project.projectId
  "attribute2": "Doejd@opsera.io", // people.email
  "mappingType": "project-memberpeople",
  "relationship": "many-to-many",
}
Code Block
200 OK

/api/v2/data/mappings

GET

Lists all mapping records for which you have access.

API Access

Code Block
languagejson
{
  "count": 1,
  "data": [
    {
      "id": "fec3d924-b2b6-41ad-8231-43e1fc0957e6"
      "attribute1": "John",
      "attribute2": "Doe",
      "mappingType": "project-member",
      "relationship": "many-to-many",
    },
  ]
}

/api/v2/data/mapping/{id}

GET

Gets the mapping record associated with the given email address.

API Access

Code Block
languagejson
{
  "id": "fec3d924-b2b6-41ad-8231-43e1fc0957e6"
  "attribute1": "John",
  "attribute2": "Doe",
  "mappingType": "project-member",
  "relationship": "many-to-many",
}

Organizational Hierarchy Mapping

URL

METHOD

DESCRIPTION

Scope

REQUEST

RESPONSE

/api/v2/data/org-hierarchy

POST

Creates an organizational hierarchy mapping record representing the organizations, businesses, departments, groups, and/or teams.

Note
Required Fields: parent, child. Representing the parent and child organization/business/department/group/team.
organization would represent the highest entities while team would represent the lowest level.

API Access

Code Block
languagejson
{
  "parent": "Opsera", // organization
  "child": "R&D", // business
}
Code Block
200 OK