GET  /presenta*on  {  

 "presenta*on":  {      "*tle":  "Best  Prac*ces  for  Designing  Hardware  APIs",      "slides":  "h>p://www.slideshare.net/Ma>Haines/best-­‐prac*ces-­‐for-­‐design-­‐iot-­‐apis"    },    "presenter":  {      "name":  "Ma>  Haines",      "company":  "Electric  Imp",      "twi>er":  "h>ps://twi>er.com/beardedinventor"    }  

}  

What  is  the  IoT  •  A  network  of  connected  devices  that  can  all  seamlessly  

communicate  with  one  another,  understand  and  interpret  each  others'  data  (as  well  as  the  context  behind  that  data)  to  ul*mately  automate  every  aspect  of  our  lives  and  pave  the  way  for  our  robot  overlords..  

•  (All  hail  our  robot  overlords)  

What  is  the  IoT  (actually)  •  The  Internet.  Everything  is  pre>y  much  the  same,  but  we  start  

connec*ng  tradi*onally  disconnected  devices,  resul*ng  in  new  a  class  of  data  and  endpoints.  This  primarily  enables  new  business  models  and  services  that  can  be  leveraged  by  marke*ng  departments!  

•  (All  hail  our  marke2ng  overlords)  

What  are  APIs  •  Applica*on  Programming  Interface  •  How  developers  interact  with  services  

•  The  glue  that  holds  the  Internet  together  and  let's  everything  communicate  with  one  another..    

Best  Prac*ces  for  Device  APIs      

h>ps://www.google.com/?q=api  best  prac*ces  

What  are  we  going  to  look  at  •  Data  formats  and  standards  •  Service  architecture  •  Security  Basics  •  Device  communica*on  strategies  •  Documenta*on  

Data  Formats  and  Standards  •  There  are  a  lot  of  'standards'  in  the  IoT  

–  Most  have  been  developed  to  solve  problems  specific  to  the  IoT  •  Low  overhead  to  decrease  memory  usage  +  increase  ba>ery  life  

•  The  'Internet'  of  Things  –  We  need  Internet  standards,  not  new  IoT  standards  

HTTPS,  JSON,  REST  •  HTTPS  –  HyperText  Transfer  Protocol  over  SSL  •  JSON  –  JavaScript  Object  Nota*on  •  REST  –  REpresenta*onal  State  Transfer  

HTTPS  •  The  Internet's  Standard  •  High  Overhead  for  some  use  cases  

–  HTTP  Streaming  /  Chunked  Responses  can  help  here  

•  Libraries  for  almost  every  language  and  framework  

JSON  •  An  Internet  Standard  

–  Probably  not  fair  to  call  it  "The"  Internet  Standard..  but  not  far  off  •  Can  be  designed  to  be  human  readable,  or  very  compact  

•  Parsing  and  encoding  libraries  for  almost  every  language  

REST  •  Soaware  Architecture  for  crea*ng  scalable  web  services  

–  Scalable  from  a  development  perspec*ve  –  Infrastructure  scaling  (managing  connec*ons,  etc)  is  its  own  problem  

•  A  lot  of  debate  in  the  web  service  community  around  REST  prac*ces  

REST(ish)  •  I  use  the  term  RESTish  to  describe  services  that  conform  to  a  

few  tenants  of  REST:  –  Resource  oriented  (we'll  get  to  this)  –  Usage  of  verbs  (GET,  PUT,  POST,  DELETE,  etc)  –  JSON  Based  (not  actually  part  of  'REST'  but  that's  ok)  

Resources  •  Web  services  should  be  designed  around  resources:  

–  An  object  with  a  type,  associated  data,  rela*onships  to  other  resources,  and  a  set  of    methods  that  operate  on  it  

•  Users,  Sensors,  Schedules,  etc  

HTTP  Methods  •  GET        Get  informa*on  about  the  resource  •  DELETE      Deletes  the  specified  resource  •  PUT      Set  the  specified  resource  (oaen  'update'  resource)  •  POST    Perform  a  server  ac*on  (oaen  'create'  resource)  

•  There  are  more  methods,  but  these  are  the  ones  we  care  about  

How  does  this  look?  An  API  for  controlling  lights  on  a  schedule:  

•  GET    /schedule  –  Get  list  of  all  schedules  •  GET      /schedule/{id}  –  Get  informa*on  about  a  schedule  •  DELETE    /schedule/{id}  –  Delete  an  exis*ng  schedule  •  POST    /schedule  –  Create  a  new  schedule  

How  does  this  look?  API  for  reading  sensors  &  modifying  configuraHon  informaHon:  

•  GET    /sensor–  Get  a  list  of  sensors  •  GET      /sensor/{id}  –  Get  informa*on  about  a  sensor  •  PUT    /sensor/{id}  –  Configure  a  sensor  

Security  Basics  •  Most  ar*cles  talking  about  IoT  security  are  actually  talking  

about  the  lack  of  security.  

•  IoT  Security  is  a  first  class  problem  –  There  are  a  lot  of  a>ack  vectors  –  Your  product  MUST  be  secure  –  This  talk  is  not  about  security..    

Symantech  Study  •  Looked  at  IoT  50  smart  devices  

–  light  bulbs,  locks,  thermostats,  smoke  detectors,  and  hubs  

•  Many  of  the  devices  had  several  "basic  security  issues"  –  Weak  Authen*ca*on  –  No  local  encryp*on  /  security  –  Web  Vulnerabili*es  (SQL  Injec*on,  unrestricted  file  uploading,  etc)  

   

(h>p://www.symantec.com/connect/blogs/iot-­‐smart-­‐home-­‐giving-­‐away-­‐keys-­‐your-­‐kingdom)  

Security  Basics  •  Security  by  obscurity  is  not  security  •  Require  HTTPS  for  all  API  calls  •  Require  authen*ca*on  •  Use  proper  /  standard  encryp*on  schemes  •  Don't  assume  the  local  network  is  friendly  •  Hire  a  security  consultant!  

Device  Communica*on  •  Your  device  shouldn't  be  running  an  HTTP  Server  •  Device  APIs  should  act  as  though  the  device  is  running  one  

•  Need  to  balance  power  constraints  and  responsiveness  –  How  "fresh"  does  data  from  the  device  need  to  be  –  What  kind  of  latency  is  acceptable  for  commands  sent  to  the  device  

Device  Communica*on  Strategies  •  Three  common  strategies  for  communica*ng  with  devices:  

1.  Device  is  always  connected  2.  Device  connects  periodically  3.  Device  only  connects  when  required    

•  Need  to  balance  responsiveness  and  power  requirements.  

 

Device  is  always  connected  •  HTTPS  request  to  API  •  Sever  process  API  and  requests  informa*on  from  device  •  Device  responds  to  server  request  with  current  informa*on  •  Server  responds  to  API  request  with  device's  data  

Device  connects  periodically  •  HTTPS  request  to  API  •  Sever  process  API  and  responds  

–  Queues  any  require  commands  –  Responds  with  'last  known'  data  points  

•  Device  periodically  connects  to  send  data  •  While  connected,  server  sends  commands  

Device  only  connects  when  required  •  Devices  have  local  control  and  monitoring  •  When  specific  criteria  are  matched,  messages  are  sent  

•  Allows  for  very  low  powered  (but  unresponsive)  devices  

Documenta*on  •  Undocumented  APIs  are  unusable  APIs  

–  How  do  you  authen*cate  –  What  are  the  end  points  –  What  does  the  data  look  like  –  What  do  errors  look  like  –  cURL  examples  or  interac*ve  API  Console  

Key  Takeaways  •  You  NEED  an  HTTPS  API    •  You  NEED  to  use  exis*ng  (Internet)  standards  •  You  NEED  to  think  about  security  (early  and  oaen)  •  You  NEED  your  API  to  respond  when  the  device  is  offline  •  You  NEED  to  balance  requirements  for  power  &  responsiveness  •  You  NEED  to  document  your  API