Download - Best Practices for Design Hardware APIs
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..
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