Burn up charts API structure proposal

[prichodko]

We need to provide the BI team with a preferred way to consume the data they aggregate. For the first version, we need epics, orphans, and repos. Let's focus on the read-only for now.

GitHub API docs itself could serve as a good starting point.

Format for the endpoints:

Get item

  GET /api/items/${id}

Parameter	Type	Description
id	string	Required. Id of item to fetch

Reponse:

[
  {
    "id": 1,
    "title": "Epic 1",
    "summary": "This is the first epic",
    "start_at": "2022-01-01",
    "end_at": "2022-03-31"
  },
  {
    "id": 2,
    "title": "Epic 2",
    "summary": "This is the second epic",
    "start_at": "2022-04-01",
    "end_at": "2022-06-30"
  }
]

[marcelines]

API structure proposal

• GET EPICS
• GET EPIC
• GET EPIC ISSUES
• GET ORPHANS
• GET REPOS

---

GET EPICS

GET /v1/epics?status=:status&search=:search&sort=:sort&milestones=:milestones&repos=:repos&startDate=:startDate&endDate=:endDate&page=:page&limit=:limit

Parameter	Type	Description
status	string	Filter by epic status. Possible values: in_progress, closed, not_started.
search	string	Search keyword for filtering epics by title and description.
sort	string	Sort epics. Possible values: title_asc, title_desc, date_asc, date_desc.
milestones	string	Filter epics by milestones. Comma-separated list of milestone IDs.
repos	string	Filter epics by repositories. Comma-separated list of repository IDs.
start_date	string	Filter epics by start at date. Format: YYYY-MM-DD.
end_date	string	Filter epics by end at date. Format: YYYY-MM-DD.
page	integer	Page number for pagination. Default: 1.
limit	integer	Number of epics to retrieve per page. Default: 10.

Response:

[
  {
    "id": 1,
    "title": "Epic 1",
    "description": "This is the first epic",
    "start_at": "2022-01-01",
    "end_at": "2022-03-31"
    "open_issues": 10,
    "closed_issues": 20,
    "data": [{
	    "date": "2022-01-03",
	    "open_issues": 29,
	    "closed_issues": 1
	    },
	    "..."
	 ],
    "label": "E:EpicName",
    "label_colour": "#5A33CA",
    "milestones": ["milestone-1", "milestone-2"]
  },
  {
    "id": 2,
    "title": "Epic 2",
    "description": "This is the second epic",
    "start_at": "2022-04-01",
    "end_at": "2022-06-30",
    "open_issues": 10,
    "closed_issues": 20,
    "data": [{
	    "date": "2022-01-03",
	    "open_issues": 29,
	    "closed_issues": 1
	    },
	    "..."
	 ],
    "label": "E:EpicName",
    "label_colour": "#5A33CA",
    "milestones": ["milestone-1", "milestone-2"]
  }
]

---

GET EPIC

GET /v1/epics/:epicId?start_date=:start_date&end_date=:end_date

Parameter	Type	Description
epicId	string	Required. ID of the epic to retrieve.
start_date	string	Start date to filter the epic's data. Format: YYYY-MM-DD. Optional parameter.
end_date	string	End date to filter the epic's data. Format: YYYY-MM-DD. Optional parameter.

Response:

{
  "id": 1,
  "title": "Epic 1",
  "description": "This is the first epic",
  "start_at": "2022-01-01",
  "end_at": "2022-03-31",
  "open_issues": 10,
  "closed_issues": 20,
  "data": [
    {
      "date": "2022-01-03",
      "open_issues": 29,
      "closed_issues": 1
    },
    "..."
  ],
  "label": "E:EpicName",
  "label_colour": "#5A33CA",
  "milestones": ["milestone-1", "milestone-2"]
}

---

GET EPIC ISSUES

GET /v1/epics/:epicId/issues?state=:state&search=:search&author=:author&labels=:labels&assignee=:assignee&repos=:repos

Parameter	Type	Description
epicId	string	Required. ID of the epic to fetch related issues for.
state	string	Filter by issue state. Possible values: open, closed.
search	string	Search keyword for filtering issues by title, description, or comments.
author	string	Filter issues by author.
labels	string	Filter issues by labels. Comma-separated list of label names.
assignee	string	Filter issues by assignee.
repos	string	Filter issues by repositories. Comma-separated list of repository names.

Response:

{
  "open_issues": 10,
  "closed_issues": 20,
  "issues": [
    {
      "id": 1,
      "title": "Issue 1",
      "state": "open",
      "author": "John Doe",
      "date": "2022-02-15",
      "labels": ["Label 1", "Label 2"],
      "link": "https://github.com/username/repo/issues/1",
      "linked_pr": "#394"
    },
    {
      "id": 2,
      "title": "Issue 2",
      "state": "closed",
      "author": "Jane Smith",
      "date": "2022-03-10",
      "labels": ["Label 3"],
      "link": "https://github.com/username/repo/issues/2",
      "linked_pr": null
    },
    "..."
  ]
}

---

GET ORPHANS

GET /v1/issues/orphans?state=:state&search=:search&author=:author&labels=:labels&assignee=:assignee&repos=:repos

Parameter	Type	Description
state	string	Filter by issue state. Possible values: open, closed.
search	string	Search keyword for filtering issues by title, description, or comments.
author	string	Filter issues by author.
labels	string	Filter issues by labels. Comma-separated list of label names.
assignee	string	Filter issues by assignee.
repos	string	Filter issues by repositories. Comma-separated list of repository names.

Response:

{
  "open_issues": 5,
  "closed_issues": 10,
  "issues": [
    {
      "id": 1,
      "title": "Orphan Issue 1",
      "state": "open",
      "author": "John Doe",
      "date": "2022-02-15",
      "labels": ["Label 1", "Label 2"],
      "link": "https://github.com/username/repo/issues/1",
      "linked_pr": "#394"
    },
    {
      "id": 2,
      "title": "Orphan Issue 2",
      "state": "closed",
      "author": "Jane Smith",
      "date": "2022-03-10",
      "labels": ["Label 3"],
      "link": "https://github.com/username/repo/issues/2",
      "linked_pr": null
    },
    "..."
  ]
}

---

GET REPOS

GET /v1/repos

Response:

[
  {
    "id": 1,
    "name": "repo-1",
    "description": "This is the first repository",
    "is_private": true,
    "total_issues": 50,
    "stars": 100,
    "link": "https://github.com/username/repo-1"
  },
  {
    "id": 2,
    "name": "repo-2",
    "description": "This is the second repository",
    "is_private": false,
    "total_issues": 25,
    "stars": 50,
    "link": "https://github.com/username/repo-2"
  },
  "..."
]

I think this what we need for the MVP, regarding the user view. @prichodko @jkbktl feel free to suggest changes.

[jkbktl]

I think it looks great. I like nested orphans under issues, so it's clear what type of orphan it is.

[prichodko]

only three remarks:

1. remove workstreams for now as we are not supporting them
2. I would use label instead of tag to stay consistent with github

3. same for summary → description API docs

[JoseAnaya28]

In our BI setup, we utilize Dremio as the component that allows you to access and extract the necessary data. To connect with this environment, you will need to use an ODBC driver, which will allow to perform direct queries on the data. Should be easier as well since I would create all the tables beforehand.

Does that work for you?