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.
Sign up for API-first, API quality, and API security sessions
Interested in hands-on workshops? Get into the tooling with these sessions:
- Introduction to APIClarity – A Wireshark for APIs – DEVWKS-2285
Barry Yuan, Technical Solutions Architect - API Security with Panoptica – DEVWKS-3002
Patrice Nivaggioli, Customer Success Manager - Creating an Open API Spec with API Insights – DEVWKS-1017
Matt DeNapoli, Manager Developer Advocacy
Want to discover and learn from others? Go to these sessions:
- API first in a CLI world, how to think about API first – DEVNET-1050
Anne Gentle, Leader, Global Developer Experience
Ray Stephenson, Sr Director, Head of Developer Relations - Extending Experiences with APIs – INTAPP-1300, Thursday, Jun 8, 11:30 – 12:15 PDT
Dexter Park, Lead Application Developer, Starbucks
Ray Stephenson, Sr Director, Head of Developer Relations, Cisco Systems, Inc.
Austin Lin, VP Product Management, Cisco Systems, Inc.
For a deeper dive into industry best practices, don’t miss these sessions:
- 18 facets of the OpenAPI standard – BRKDEV-2249
Steve Sfartz, Principal Architect - API Design-First – Not Just Another Pretty Interface – DEVNET-2092
David Staudt, Developer Advocate - Why API Contracts matter – DEVNET-1346, Monday, Jun 5, 4:00 PM – 4:45 PM PDT
Steve Sfartz, Principal Architect
In the meantime, learn from these developer resources
If you cannot join Cisco Live in person, please check the daily DevNet readout/takeaways with our live broadcast.
Also, every session (except workshops) will go to Cisco Live on-demand in a few weeks.
You can always experience interactive documentation on developer.cisco.com/learning and try our Learning Labs or reserve a Sandbox to try out Cisco programmable technology for free.
We’d love to hear what you think.
Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!
LinkedIn | Twitter @CiscoDevNet | Facebook | YouTube Channel
CONNECT WITH US