Parts of an Augur API Endpoint
Develop the query that will produce data needed to deliver the endpoint, usually parameterized by a repo_id.
Determine if the endpoint will be a “standard endpoint”, or a custom endpoint.
Where Are the Endpoints?
JSON Metrics are here:
$ AUGUR_HOME/augur/metrics
Visualization Metrics are here:
$ AUGUR_HOME/augur/routes
Existing metrics files (JSON Metric) “Standard Metrics”:
commit.py
contributor.py
experimental.py
insight.py
issue.py
message.py
platform.py
release.py
repo_meta.py
All “Standard Metrics” files generally share a set of imports
import datetime
import sqlalchemy as s
import pandas as pd
from augur.util import register_metric
You can see that one of the imports is our standard metric import from the util file, which is located in:
AUGUR_HOME/augur/routes/util.py
All “Standard Metrics” share declaration and a method signature
Declaration:
@register_metric()
Method Signature:
def contributors(self, repo_group_id, repo_id=None, period='day', begin_date=None, end_date=None):
Standard metrics also, generally, include default setting blocks for date range, in the event parameters are not passed.
if not begin_date:
begin_date = '1970-1-1 00:00:01'
if not end_date:
end_date = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
There is also, generally, a block in a standard metric for pulling data by a repo_id or a repo_group_id. The default is a repo_group_id. Here is an abrdiged example from the contributors endpoint in contributor.py
if repo_id:
contributorsSQL = s.sql.text("""
SELECT id AS user_id,
SUM(commits) AS commits,
SUM(issues) AS issues,
SUM(commit_comments) AS commit_comments,
SUM(issue_comments) AS issue_comments,
SUM(pull_requests) AS pull_requests,
SUM(pull_request_comments) AS pull_request_comments,
SUM(a.commits + a.issues + a.commit_comments + a.issue_comments + a.pull_requests +
a.pull_request_comments) AS total,
a.repo_id, repo.repo_name
FROM (
(SELECT gh_user_id AS id,
ommitted_lines as ommitted_from_example
AND created_at BETWEEN :begin_date AND :end_date
GROUP BY id, repo_id
)
) a, repo
WHERE a.repo_id = repo.repo_id
GROUP BY a.id, a.repo_id, repo_name
ORDER BY total DESC
""")
results = pd.read_sql(contributorsSQL, self.database, params={'repo_id': repo_id, 'period': period,
'begin_date': begin_date, 'end_date': end_date})
else: ## This is if the repo_id is not specified
contributorsSQL = s.sql.text("""
SELECT id AS user_id,
SUM(commits) AS commits,
SUM(issues) AS issues,
SUM(commit_comments) AS commit_comments,
SUM(issue_comments) AS issue_comments,
SUM(pull_requests) AS pull_requests,
SUM(pull_request_comments) AS pull_request_comments,
SUM(a.commits + a.issues + a.commit_comments + a.issue_comments + a.pull_requests +
a.pull_request_comments) AS total, a.repo_id, repo_name
FROM (
(SELECT gh_user_id AS id,
repo_id,
0 AS commits,
COUNT(*) AS issues,
0 AS commit_comments,
AND created_at BETWEEN :begin_date AND :end_date
GROUP BY id, repo_id
ommitted_lines as ommitted_from_example
)
) a, repo
WHERE a.repo_id = repo.repo_id
GROUP BY a.id, a.repo_id, repo_name
ORDER BY total DESC
""")
results = pd.read_sql(contributorsSQL, self.database, params={'repo_group_id': repo_group_id, 'period': period,
'begin_date': begin_date, 'end_date': end_date})
return results
Existing Visualization Metrics Files:
augur/routes/contributor_reports.py
augur/routes/pull_request_reports.py
Existing Metrics Files:
augur/metrics/commit.py
augur/metrics/contributor.py
augur/metrics/deps.py
augur/metrics/experimental.py
augur/metrics/insight.py
augur/metrics/issue.py
augur/metrics/message.py
augur/metrics/platform.py
augur/metrics/pull_request.py
augur/metrics/release.py
augur/metrics/repo_meta.py
These files are not intended to be all inclusive. Rather, they are what we have developed, or imagined, based on existing CHAOSS metrics to date. New CHAOSS metrics are likely to result in the inclusion of new files under metrics, or routes, depending if they are standard metrics or not.