Design before you code. Full lifecycle API engineering

By K.P., Portal back-end designer

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. 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
Just as 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.

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 imbed 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 lets you write simple YAML on the left screen and watch the documentation render 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. The Developer Program team liked this tool enough to pull it onto our portal as a Swagger Editor page.

OpenAPI GUI is the other open-source tools that has a fan on our Developer Program team. It 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. OpenAPI GUI is under active development and is rapidly evolving.

Our back-end API designer, K.P., 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.)

K.P. 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.”

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.