I was profiling the volume of API from the Internet of Things platform Predix this last week. Luckily, they have OpenAPI definitions for each of the APIs, something that makes my life a lot easier. As they have a wealth of APIs available, doing an amazing amount of work when it comes to connecting devices to the Internet — I love their enthusiasm for putting out APIs. My only critical feedback for them after working my way through their API definitions is that they should invest some time to develop an API design guide and distribute it across their teams. The wild variances in definition and design of their APIs made me stumble a number of times while learning about what they do.
While looking through the definitions for the Predix APIs, I found many inconsistent patterns between them, and you could tell that they had different teams (or individuals) working across the suite of APIs. The inconsistencies ranged from the naming, description, and how the metadata was provided for each API, all the way to acronyms used in API paths, and other things that prevented me from understanding what an API did all together. While I am stoked they provide OpenAPI definitions for all of their APIs, I still struggled to understand what was possible with many of their APIs. It kind of feels like they need an external editor to review each API definition before it leaves the door, as well as some sort of automated validation using JSON schema, that would work against a common set of API design standards.
from DZone.com Feed https://ift.tt/2LN947f
No comments:
Post a Comment