[RFC] Proposed V1 API

[EvanSimpson]

Versioning is to be handled in the Accept Header.

  // API key settings routes
  router.all('/api/user/apikey*', Oauth.authenticate);
  router.get('/api/user/apikey', Config.apiKey); // get existing API key
  router.post('/api/user/apikey', Config.genApiKey); // create and get new API key

  // Authenticate API routes with API key
  router.all('/api/tessel*', App.authenticate);

  // Tessel routes
  router.post('/api/tessel', Tessels.create); // create new remote Tessel
  router.get('/api/tessel/:device_id', Tessels.details); // list details for one Tessel
  router.put('/api/tessel/:device_id', Tessels.update); // update Tessel nickname/ allowed users
  router.delete('/api/tessel/:device_id', Tessels.delete); // delete remote Tessel
  router.get('/api/tessel', Tessels.list); // list details for all of user's Tessels

  // Remote control routes
  router.put('/api/tessel/:device_id/code', remote.code); // tessel run or push as decided by attributes
  router.get('/api/tessel/:device_id/network', remote.network); // get network connection details
  router.get('/api/tessel/:device_id/log', remote.log); // start listening/get details to start a listening connection - however this ends up being done

Message protocol

• Command code - 8 bit
• File length - 64 bit
• File checksum - 16 bit CRC
• File data - 'length' bytes

  Potential Command Codes

0x01 Push 0x02 Run 0x03 - 0x06 Reserved 0x07 Network status 0x08 Get logs 0x09 - 0xFF Reserved

[tcr]

Granted if we are doing all this under a /api/ route, we might as well use Accept headers to denote distinguishing API versions.

[tcr]

Is /user/ also a JSON-based API?

[tcr]

  router.get('/v1/tessels', Tessels.list); // list details for all of user's Tessels

The list of tessels should be exposed as part of a user's profile, if not user/me/tessels.

  // Remote control routes
  router.put('/v1/run/:device_id', remote.run); // tessel run
  router.put('/v1/push/:device_id', remote.push); // tessel push
  router.get('/v1/listen/:device_id', remote.listen); // tessel listen
  router.get('/v1/network/:device_id', remote.network); // tessel wifi -l

Pretty un REST-ful. I'd propose

PUT /v1/tessel/:device_id/code (with a flag for flash: true or flash: false)
GET /v1/tessel/:device_id/networks
GET /v1/tessel/:device_id/log (does this tail?)

Also, specify that :device_id 404 when not authenticated.

[EvanSimpson]

/user/ would be JSON, yes.

How would you propose distinguishing a run from a push?

[tcr]

The should /user/ be /api/user/?

Run has flash=false and push has flash=true. Then there's a runimmediate=true attribute too maybe?

[tcr]

Also: http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/ and application/vnd.tessel.remote.v1

[EvanSimpson]

We can drop the /v1/ and put everything under /api/ I think run/push are deliberate enough that runimmediate would always be true.

[EvanSimpson]

Updated routes.

[tcr]

 router.post('/api/user/tessel', Tessels.create); // create new remote Tessel
  router.get('/api/user/tessel/:device_id', Tessels.details); // list details for one Tessel
  router.put('/api/user/tessel/:device_id', Tessels.update); // update Tessel nickname/ allowed users
  router.delete('/api/user/tessel/:device_id', Tessels.delete); // delete remote Tessel

All these should be /api/tessel.

[EvanSimpson]

That's really overloading PUT and GET.

[tcr]

All of those should not be at /api/user/tessel/..., but /api/tessel/....

[EvanSimpson]

Nevermind - see your other suggestions now.