Sign up for API-first, API quality, and API security sessions

Seeing “Let’s Go!” in large letters, as the theme for Cisco Live US, reminds me of the soccer announcer’s “Gooooooooooaaaaaaaallllllllll” cry. This reminder excites me for the rest of Ted Lasso’s season 3. My mind makes these connections for football, er, soccer, and Cisco Live.

Like the best examples of coaches are the ones with the best win/loss record, the same goes for Cisco APIs. And sometimes, the best coaches look for continuous improvement rather than winning at all costs. We continue to work with engineering teams to improve Cisco APIs over time, and our coaching has yielded some excellent examples, which you can learn about at Cisco Live US in June 2023.

Learn what Cisco has been up to in API design and implementation

You may have seen the Cisco API-first announcement starting with backward compatibility for seven flagship Cisco APIs in November 2022. You will be able to see the tool that helps detect backward compatibility by getting a demo of API Insights in the DevNet Zone. The API Insights demo shows how we can compare two OpenAPI documents. Cisco joined the OpenAPI initiative in mid-2022. By comparing the changes in OpenAPI documents across releases, teams can generate changelogs for APIs and track changes over time. We share a preview of the new API Insights version used internally, which will be updated as open source in summer 2023. This preview shows automation abilities for generating changelogs and identifying unwanted breaking changes. After handling large OpenAPI documents with hundreds of thousands, even millions of lines, we can show you our findings. You want to stop by and see this demo. And we want to hear your API design questions.

Improving your developer experience

We also want to know your experience with API documentation at developer.cisco.com. Please go to the Design Thinking Area of the DevNet Zone, share your experience, discover the recent changes in the developer portal, and provide feedback on future developments. Designers are there all week to learn from your experiences. Please stop by, complete our survey, and go through a well-honed design thinking experience.

Inclusive language in API design

We believe in the power of words at Cisco and have incorporated testing for our inclusive language policy within our API Insights tool. When biased terms such as master, slave, blacklist, or whitelist are detected in an OpenAPI document, the API Insights toolset notifies and lists suggested alternatives.

We recently investigated how to handle biased language in a released API. We came up with three potential approaches:

The “New only” approach uses the inclusive term only for the new creation of an object. Think of the main/master default branch name switch that GitHub implemented as a good example.
The “Rip off the Band-Aid” approach for JSON payloads returned from an API, for example. Inform developers that depending on the current API version, it’ll return masterDevice/slaveDevices, and in the next version, it’ll return controlDevice/dataDevices.
The “Alias” approach for the API design allows both terms to work for a designated amount of time and update the API documentation to promote the newer approach. For example, this approach could work for biased terms in endpoint paths. You want to give some planning and time to move to the inclusive term.

If you are interested in such design discussions, please stop by the API Quality Demo pod in the DevNet Zone and share your learnings and best practices.