Proposal for Code::Stats profile API request format

1_README.md

Request format

JSON object key is ID that will be returned with the data and value is request specification.

Request specifications

Three keys: target, group and time.

Target means what data should be returned. Can be xp for total XP amounts, language for XP split by language, or machine for XP split by machine.

Group means grouping of data. total means no grouping, amounts are sent as is. Other values group the data into a list of group objects. Valid values are: 5min, 15min, 30min, hour, day, month, year (these group the data into time based groups).

Time means range of time from where data is retrieved. total is only available if group is also total, it returns totals since the user was registered. Otherwise the value can be a single RFC3339 datetime for returning from that time to current time or a list of two RFC3339 datetimes representing the start and end points of the time range. Time range is 30 days maximum.

Group objects

If data is grouped, it's returned in group objects:

{
  "id": "2017-10-30T00:00:00Z",
  "data": ...
}

The ID depends on the grouping type. If the grouping is based on time, the ID will be an RFC3339 datetime rounded down to the starting datetime of the group.

example.json

{
  "total_langs": {
    "target": "language",
    "group": "total",
    "time": "total"
  },

  "last_12h_langs": {
    "target": "language",
    "group": "total",
    "time": "2017-10-15T14:55:00Z"
  },

  "total_weekly_xp": {
    "target": "xp",
    "group": "day",
    "time": "2017-10-09T00:00:00Z"
  },

  "last_months_languages": {
    "target": "language",
    "group": "total",
    "time": ["2017-09-01T00:00:00Z", "2017-09-30T23:59:59Z"]
  }
}

output.json

{
  "total_langs": {
    "C++": 15,
    "PHP": 0,
    "Elixir": 100
  },

  "last_12h_langs": {
    "Python": 99,
    "Ada": 101
  },

  "total_weekly_xp": [
    {
      "id": "2017-10-09T00:00:00Z",
      "data": 4014
    },
    {
      "id": "2017-10-10T00:00:00Z",
      "data": 1024
    },
    {
      "id": "2017-10-11T00:00:00Z",
      "data": 386
    },
    {
      "id": "2017-10-12T00:00:00Z",
      "data": 6736
    },
    {
      "id": "2017-10-13T00:00:00Z",
      "data": 1245
    },
    {
      "id": "2017-10-14T00:00:00Z",
      "data": 3452
    },
    {
      "id": "2017-10-15T00:00:00Z",
      "data": 3525
    }
  ],

  "last_months_languages": {
    "D": 176,
    "BASIC": 995,
    "FORTRAN": 19
  }
}

• How about Levelprogression? Language x at level 1 at 10% / 2000xp left to level up
• Maybe compare two groups? Language x earned 10% more xp than last week

@PhilippHandle

Level progression can be handled by the client so it does not need to be in the API. The latter could be calculated by the client by getting the last two weeks' language data.

I got a good suggestion to look at GraphQL so I'm going to do that next to see if it would cover the API nicely. Btw if you have comments, it's faster to say on the Gitter channel: https://gitter.im/code-stats/Lobby (I almost didn't see your comment here as GitHub didn't notify me!). :)