Design before you code: full-lifecycle API engineering

By Warren Volkmann, Editor
HP Developers Portal


The idea that you can design an API without writing code just seems somehow backwards, like putting the cart before the horse. But “full lifecycle API engineering” is an emerging field with a new set of tools that let you do just that. Just as you don’t need to hammer nails to design a house, neither do you need to code to initially design and document an API.

Design first, code later

Much like how test-driven development (TDD) puts feature-coding subsequent to consideration of test-cases, the premise behind full-lifecycle API engineering is that an API team can most quickly reach alignment with its API consumers by designing the API first – before committing any code. This is akin to customer-centric, lean product design, where designers render concepts and solicit consumer feedback before any technical specs are detailed. Given the emerging craze for VR, imagine a home builder taking a customer on a virtual tour of a house to see if they like the floor plan. (House shopper: “Can we put the bedrooms on the left of the hallway so they have a view?” Builder: “Let me flip that part of the layout. Now let’s see how that changes access to the garage.”) 

For API developers, designing before coding helps avoid overlooking required functions or sinking a lot of time and energy into unwanted features. Once an API product has earned design approval, then coders can proceed in the most efficient manner to flesh out the features and capabilities of the service. Plus the app developers can proceed with their work, knowing that the functions they want are being coded.

Design-first applied to Swagger

The Swagger specification, which recently evolved into the “OpenAPI Specification,” is being widely adopted to facilitate automatic generation of API documentation. It is a definition format for describing RESTful APIs. The Swagger spec allows developers to embed documentation, free of style overhead, down at the code level – no more tech writers chasing around trying to find out what changed in the latest API release. The essential documentation is right there next to the code. It can be drawn out during the build or continuous integration stages to automatically render up-to-date, web-accessible docs.

Working with Swagger typically entails incorporating libraries like Swagger UI and Swagger Codegen. The Swagger community has made life a lot easier for API and app developers by providing many tools that facilitate Swagger API specification design and rendering. Two emerging tools enable API-first design of Swagger documentation:

Swagger Editor

Swagger Editor lets you write simple YAML on the left screen and watch the documentation render in real time on the right.

Swagger Editor provides a handy shortcut for auto-generating client SDKs. Want that turned in Ruby? Java? Python? Perl for all you Old Schoolers? Pick your passion from the 37 options in the “Generate Client” dropdown menu.

Swagger Editor can also “Generate Server” with 23 options including Spring, Node.js, or Rails5.

OpenAPI GUI

Another emerging, open-source tool that has a fan at our Developer Program team is OpenAPI GUI at https://mermade.github.io/openapi-gui/. This design tool is similar to Swagger Editor, but it dismisses the YAML code pane in favor of an assortment of on-screen buttons. The buttons provide an interactive, see-as-you-go, API-docs design experience, based on top of Swagger. When you like what you see, you can kick out Swagger-JSON or YAML.

Our back-end API designer, Krishna Prasad, praises OpenAPI GUI , which he refers to as “Mermade” because it is hosted on Github by Mermade Software in England. (Note the novel spelling. It’s “mermade” not “mermaid.” We suspect M-E-R is initials for Mike Ralphson. Software made by M.E.R. is then, by definition, MERmade. Clever lad.)

Our Krishna Prasad had this to say about OpenAPI GUI: “Originally it was taking three to four hours to create Swagger documentation with 2 operations. Now with this tool, I can accomplish it in 30 minutes. This is making my life easier and allowing me to have a specification ready in a much shorter time.”

Inside HP, the Developer Program team is always scouting for new and better tools like Swagger Editor and OpenAPI GUI. We are actively learning and disseminating useful patterns – like API-first product engineering. We welcome you to share your insights and ideas about these emerging tools. Or tell us about your favorites.


Other popular posts on the HP Developer Portal