Ohhh, this is such a great question! Also, it's quite clear you’ve seen these systems & their APIs up close, and can appreciate the mess… :)
So I’d say there are two approaches to doing these abstractions. We sort of support both and let the API client decide which way they want to roll.
The first approach consists of stripping away all the “stuff” that stands in the way of controlling a device. We basically just boil everything down to atomic operations on a single device. For example on SaltoKS locks, we let you create access codes directly on a door devices without having to worry about creating users, access groups, schedules…etc. Of course, we have to create these behind the scenes, but we don’t expose them to the API client. Instead we give you simple methods such seam.access_code.create(device_id…etc) that you can use against either an August device or one that’s part of a larger system such as SaltoKS.
The second approach consists of reintroducing the concept of users, access groups, and assigned credentials…etc and to lift the abstraction to entire systems vs just individual devices/nodes. You frankly need to do this if the site owner wants to continue to use their system in a sensible manner (e.g. see list of employees who badged in) or if you want to support more complex forms of credentials (e.g. Google/Apple Wallet).
I think the important thing to recognize is that, at the end of the day, whether you choose abstraction 1 or abstraction 2, these devices/systems all more or less do the same thing. The manufacturer may use slightly different terminology but you can create abstractions from that.
ps: btw for a long-time we made the mistake of spending too much time trying to nail the abstraction on every dimension imaginable. This included features of certain systems that no developers were asking us about. Now we just focus on solving what devs are asking for. That reduces the surface area of how much "stuff" we have to deal with when creating these API interfaces. This is a textbook example of going back to the YC basics of "talk to users" and "build something people want".
So I’d say there are two approaches to doing these abstractions. We sort of support both and let the API client decide which way they want to roll.
The first approach consists of stripping away all the “stuff” that stands in the way of controlling a device. We basically just boil everything down to atomic operations on a single device. For example on SaltoKS locks, we let you create access codes directly on a door devices without having to worry about creating users, access groups, schedules…etc. Of course, we have to create these behind the scenes, but we don’t expose them to the API client. Instead we give you simple methods such seam.access_code.create(device_id…etc) that you can use against either an August device or one that’s part of a larger system such as SaltoKS.
The second approach consists of reintroducing the concept of users, access groups, and assigned credentials…etc and to lift the abstraction to entire systems vs just individual devices/nodes. You frankly need to do this if the site owner wants to continue to use their system in a sensible manner (e.g. see list of employees who badged in) or if you want to support more complex forms of credentials (e.g. Google/Apple Wallet).
I think the important thing to recognize is that, at the end of the day, whether you choose abstraction 1 or abstraction 2, these devices/systems all more or less do the same thing. The manufacturer may use slightly different terminology but you can create abstractions from that.
ps: btw for a long-time we made the mistake of spending too much time trying to nail the abstraction on every dimension imaginable. This included features of certain systems that no developers were asking us about. Now we just focus on solving what devs are asking for. That reduces the surface area of how much "stuff" we have to deal with when creating these API interfaces. This is a textbook example of going back to the YC basics of "talk to users" and "build something people want".