I rarely write posts about my day job on this blog, the focus of this blog is to address my hobbies and passions.  When those intersect with my day job I will try and post a few thoughts.  Having said that, I recently took a new job focusing on improving the API strategy of IBM’s Engineering Lifecycle Management offering (ELM).  

IBM ELM is a tool suite utilized by the world’s most successful companies which design, develop and deliver vehicles of all kinds (Planes, Trains, and Automobiles – and more)!  The suite of capabilities  was built on the idea of open development.  The team has been developing this publicly for well over a decade, and has built an incredible community at jazz.net. 

The basic, underlying APIs have been exposed via a standard called OSLC (Open Services for Lifecycle Collaboration).  This OSLC standard is is being maintained and enhanced via Open Oasis. 

One of the coolest things about OSLC based APIs is that they are highly discoverable at runtime when working on building integration between systems.  In ELM, we expose many services via a “RootServices” document on each server.   By parsing this document, APIs (or services) are exposed, and their definitions are exposed.  

I’ve been working on a example of how to parse this via a set of Postman examples to help new developers understand this technology.  This example will show, how to parse a RootServices document, perform a simple OAuth1.0a authentication, and then expose the definition of a specific API and the data that must be provided to create a system artifact.  Right now my example shows how to create a Automated Test Adapter.

I hope to do some cleanup of my example over the next few weeks and will post it here; however, I would like to understand what other types of open API documentation people would like to see.