API Design

[sondr3]

REQUIRED:

• Real-time coffee information
• Historical coffee information
• System information
• Version API

WANTED:

• Card scanning information

NOTES:

• Only GET requests

DESIGN:
Route design: /v1/coffee/<year>/<month>/<day>.

Example, GET /v1/coffee:

{
  "time": "20190120T120345Z1",
  "coffee": {
    "temperature": 1000,
    "cups": -10,
    "amount": 1,
  },
  "mocca": {
    "isPowered": true,
    "startedBrewing": "20190120T120345Z1",
    "lostPower": true,
    "outages": {
      ["20190120T120345Z1", "20190120T120345Z1"],
      ["20190120T120345Z1", "20190120T120345Z1"],
    },
  }
}

If lostPower is true, outages returns a list where the first element is when it was powered on and the second element is when it was powered off. If lostPower is false, outages returns null.

Example, GET /v1/coffee/2019/01/16:

{
  "20190120T120345Z1": {
    "time": "20190120T120345Z1",
  "coffee": {
    "temperature": 1000,
    "cups": -10,
    "amount": 1,
  },
  "mocca": {
    "isPowered": true,
    "startedBrewing": "20190120T120345Z1",
    "lostPower": true,
    "outages": {
      ["20190120T120345Z1", "20190120T120345Z1"],
      ["20190120T120345Z1", "20190120T120345Z1"],
    },
  }
}

[sondr3]

Per #9, the API is slight different than how this document lists it. The only difference is that the outages field in mocca is now a Duration instead of a list of DateTimes that list when it lost power and when it regained power. As it stands now it looks like this right now:

{
    "time": "2019-02-08T18:55:04Z",
    "coffee": {
        "temperature": 18, 
        "cups": 5,
        "amount": 3
    },  
    "mocca": {
        "is_powered": false,
        "started_brewing": "2019-02-08T18:55:04Z",
        "lost_power": true,
        "outages": "00:33:21"
    }   
}

[sondr3]

Per the latest changes in #9, the API has been updated according to feedback from Albin, we've merged cups/amount in coffee, changed temperature and amount to be floats and removed lost_power in mocca (we can check outages for null instead):

{
    "time": "2019-02-08T18:55:04Z",
    "coffee": {
        "temperature": 18.2,
        "amount": 0.3
    },
    "mocca": {
        "is_powered": false,
        "started_brewing": "2019-02-08T18:55:04Z",
        "outages": "00:33:21"
    }
}

Furthermore, the API has evolved ever so slightly. Instead of being api/coffee/, we now have versioning and two endpoints instead. /api/v1/coffee/ return the 10 latest readings from the sensor while api/v1/coffee/now returns a single reading, the latest one. This was motivated primarily because when trying to only return the latest reading from api/coffee would be surprising to people as they would expect it to be a list.

[sondr3]

With the latest changes done in #16, #17 and #18, the fields are better documented in the Swagger interface, the time field has been changed to measured_at to better reflect what is actually is, is_powered has become an int field between three choices and the whole API has been flattened instead of nesting the coffee and mocca fields.

{
    "measured_at": "2019-02-08T18:55:04Z",
    "is_powered": 0,
    "started_brewing": "2019-02-08T18:55:04Z",
    "temperature": 18.2,
    "amount": 0.3,
    "outages": "00:33:21"
}

[sondr3]

I've done a minor refactor of the API in the hackathon branch, the is_powered field has been renamed to status as this better reflects what the actual field is. is_powered sounds to me like a boolean on/off field instead of a (off, heating, brewing) field. The ID is also included now due to React. It now looks like this:

{
  "id": 223,
  "measured_at": "2019-04-08T17:42:09.723021+02:00",
  "temperature": 45,
  "amount": 0.5,
  "status": 1,
  "brew_started": "2019-04-30T00:00:00+02:00",
  "brew_outages": "00:00:00"
}