Generating OpenAPI Specs For The Mobile Apps You Depend On Just By Using Them
16 Feb 2016
Stoplight.io is a very cool new API modeling and proxy tool. I just wrote a post about the overall features of the platform, but I wanted to zoom in on a specific benefit that Stoplight.io brings to the table--the auto generation of OpenAPI Specs, for the mobile apps you depend on, as you use them. To understand the process in detail, I recommend watching the how was this created video on the Peach API documentation generated by Stoplight.io.
When you download the Stoplight API designer for Mac (available on the account dashboard), you get the Prism API Proxy, which allows you to easily route all the traffic from your Macbook, as well as iPhone and IPad, through the platform. Once you create a new API, add the base URL for the API you are profiling, StoplLight does the rest, automatically generating an OpenAPI Spec, and attractive API documentation in the application, in real time as you watch--it is pretty cool to watch once you have turned on.
Why do I want to do this? Well first of all, I am someone who has spent five years traveling around the world wearing the same t-shirt evangelizing APIs to everyone who will listen--obviously I have a number of problems. Beyond that, I'm fascinated by the API design practices of the leading "dark APIs" I use everyday, but rather than doing so via a public API program, it is via a mobile device. I'm fascinated by this layer of the API sector, one that is fueling all of the API growth we are seeing, but getting a much smaller portion of the conversation that is dominated by leading public APIs.
To help me learn about what is possible with StopLight, I profiled the APIs that LinkedIn and Instagram mobile applications used. It took me about 15 minutes to go through each application, and hit publish on the documentation you see published to API Docs. I feel that there are many lessons to be extracted by the API designs behind these leading applications, and continue providing lessons when you compare these API design strategies with the public API design strategies for the same companies.
I am not sure where all of this will lead. I know that profiling the APIs behind mobile applications is something many feel we shouldn't be doing, something I will write about separately, but I can't help but feel the opposite. In my opinion you should be proud of any APIs you make publicly available to drive any web, mobile, or device applications, and we should be having serious conversations around security, privacy, monetization, and other critical things that are increasingly happening in this shadowy layer of our digital lives.