Apigee’s latest efforts to power digital acceleration aim to fill in gaps in the API lifecycle that can spell the difference between API success – or a flop. Apigee-127 brings together key tools, including Swagger, for a ‘design-first’ way to deliver accurate and easier-to-consume APIs. IDN speaks with Apigee’s Jeff West.

"Having a good API design, and sticking to it, is just as important as UI design."

Apigee’s latest efforts to power digital acceleration aim to fill in gaps in the API lifecycle that can spell the difference between API success – or a flop. Apigee-127 brings together key tools, including Swagger, for a ‘design-first’ way to deliver accurate and easier-to-consume APIs.

“We found having a good API design, and sticking to it, is just as important as UI design,” West said. It’s this discovery that he said is driving Apigee-127, which aims to benefit many companies looking to improve their API success rate, boost API adoption and speed API deliveries.

This traditional way of working on APIs, West said, can “create friction” on a couple of fronts. Notably:

It slows down APIs projects and

After APIs are delivered, they don’t always work as originally intended. Apigee-127 looks to set the API design in place, and ensure all others comply with that design.

So, to avoid these ‘friction’ points, West detailed some top reasons why taking a ‘design-first” approach to API projects (and staying with that design all the way to launch). Keeping these principals in mind, he added, are important to achieving API success.

Apps enable and define experiences for their users. They aren’t just endpoints.

Poor API design equals slow adoption

Creating the server before the client is “a surefire way” to build the wrong API

Design APIs for consumption is done best when done at the beginning of a development process – not at the end, and certainly not improvised at multiple points downstream

Apigee-127 includes these tools to help devs implement and deliver a ‘design first’ API approach:

A Swagger 2.0 Editor running locally, built for the Swagger Community by Apigee. The editor lets devs design, build and test APIs with easy-to-learn YAML configuration. This allows devs to use YAML to author their API specs, and auto-generate documentation.

Volos.js middleware adds value to your API with features such as Caching, Quota and OAuth 2.0. Users can add Volos.js features directly in Node.js code, or, with Swagger Tools extensions, configure them directly in YAML in the Swagger editor.

Add it all up, and Apigee-127’s design-first (or model-first) approach lets designers define the API structure in Swagger 2.0, the popular API framework, and then define the business logic in JavaScript, a simple, easy and popular dev language, West noted.

Inside The Motivation That Drove Apigee-127 – Hands-On Case Studies

Apigee’s West shared some background with IDN on the genesis behind the idea for Apigee-127, and how it addresses some common problems companies face in the design-to-deploy API lifecycle.

“When we were building our APIs, we designed what API we wanted to interact with our Apigee API Management features. Then our development team would build something and rationalize it against the original API design,” West said.

“We found out this [problem] happens with many companies working with API projects. Even after the [API] design is all set up, an engineer or someone else [downstream] thinks they have a better idea for how fast or how much data an API can deliver. That’s when an API project can go wrong,” West added.

APIs for mobile apps are a great example, he continued. “APIs for mobile apps are designed to provide very customized data to the app – no more or less than the app really needs,” West said. “If you change that design, you end up with an API that doesn’t work best for the app.”

West shared this example:

“Say you are building a mobile app for a pet store that just wants data on cats and dogs. Someone later says to himself, ‘I can make this better. I’ll deliver ‘all pets,’ not just cats and dogs. That way, the app can set the parameter of what they want.’ So, the developer or engineers make those types of changes that make sense to them. But, changing the design just creates hiccups in the [API] lifecycle.”

One idea that makes Apigee’s approach to design-first APIs is that it is not all about carrying a big stick to ensure compliance. Including Swagger delivers many benefits, not only to downstream engineers, but to folks responsible for coding, documentation and adoption.

“Swagger is attractive for a number of reasons. It is already widely-adopted and easy-to-learn,” West noted. “On top of that, from Swagger, you can generate documentation and even an SDK that lets people more easily learn and use an API. Starting from a YAML file, with Apigee-127 devs can create API documentation, generate client SDKs in several languages – Java, Scala, JavaScript, PHP, Python, Ruby, or generate server stubs in Java, Scala, Ruby or JavaScript. This cuts a lot of the skills gap, because developers can use their existing knowledge, such as with Javascript, for example, and won’t need to learn Node.js,” West added.

Apigee-127 also relieves another stress point in the API lifecycle – testing pre-launch testing, West told IDN.

“It’s really great for API business ideas because you can return mock responses [from datasets] before you implement the API. Hands down, our customers want this kind of mock capability,” he said. One big benefit is that companies can easily test out an idea for an API, and let users (internal users or outside partners) quickly work with it and see if it will work, or if they need to iterate a better version.