Seeing “Let’s Go!” in massive letters, because the theme for Cisco Stay US, jogs my memory of the soccer announcer’s “Gooooooooooaaaaaaaallllllllll” cry. This reminder excites me for the remainder of Ted Lasso’s season 3. My thoughts makes these connections for soccer, er, soccer, and Cisco Stay.
Like the very best examples of coaches are those with the very best win/loss document, the identical goes for Cisco APIs. And generally, the very best coaches search for steady enchancment relatively than profitable in any respect prices. We proceed to work with engineering groups to enhance Cisco APIs over time, and our teaching has yielded some wonderful examples, which you’ll be able to study at Cisco Stay US in June 2023.
Study what Cisco has been as much as in API design and implementation
You might have seen the Cisco API-first announcement beginning with backward compatibility for seven flagship Cisco APIs in November 2022. It is possible for you to to see the software that helps detect backward compatibility by getting a demo of API Insights within the DevNet Zone. The API Insights demo reveals how we are able to evaluate two OpenAPI paperwork. Cisco joined the OpenAPI initiative in mid-2022. By evaluating the modifications in OpenAPI paperwork throughout releases, groups can generate changelogs for APIs and observe modifications over time. We share a preview of the brand new API Insights model used internally, which shall be up to date as open supply in summer season 2023. This preview reveals automation skills for producing changelogs and figuring out undesirable breaking modifications. After dealing with massive OpenAPI paperwork with a whole bunch of hundreds, even tens of millions of strains, we are able to present you our findings. You need to cease by and see this demo. And we need to hear your API design questions.
Enhancing your developer expertise
We additionally need to know your expertise with API documentation at developer.cisco.com. Please go to the Design Pondering Space of the DevNet Zone, share your expertise, uncover the latest modifications within the developer portal, and supply suggestions on future developments. Designers are there all week to study out of your experiences. Please cease by, full our survey, and undergo a well-honed design considering expertise.
Inclusive language in API design
We imagine within the energy of phrases at Cisco and have integrated testing for our inclusive language coverage inside our API Insights software. When biased phrases corresponding to grasp, slave, blacklist, or whitelist are detected in an OpenAPI doc, the API Insights toolset notifies and lists advised alternate options.
We lately investigated how you can deal with biased language in a launched API. We got here up with three potential approaches:
- The “New solely” method makes use of the inclusive time period just for the brand new creation of an object. Consider the primary/grasp default department title swap that GitHub carried out as a very good instance.
- The “Rip off the Band-Assist” method for JSON payloads returned from an API, for instance. Inform builders that relying on the present API model, it’ll return masterDevice/slaveDevices, and within the subsequent model, it’ll return controlDevice/dataDevices.
- The “Alias” method for the API design permits each phrases to work for a chosen period of time and replace the API documentation to advertise the newer method. For instance, this method may work for biased phrases in endpoint paths. You need to give some planning and time to maneuver to the inclusive time period.
If you’re focused on such design discussions, please cease by the API High quality Demo pod within the DevNet Zone and share your learnings and greatest practices.
Join API-first, API high quality, and API safety classes
All in favour of hands-on workshops? Get into the tooling with these classes:
Wish to uncover and study from others? Go to those classes:
- API first in a CLI world, how to consider API first – DEVNET-1050
Anne Mild, Chief, World Developer Expertise
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 Software Developer, Starbucks
Ray Stephenson, Sr Director, Head of Developer Relations, Cisco Programs, Inc.
Austin Lin, VP Product Administration, Cisco Programs, Inc.
For a deeper dive into business greatest practices, don’t miss these classes:
Within the meantime, study from these developer assets
For those who can’t be part of Cisco Stay in individual, please test the day by day DevNet readout/takeaways with our stay broadcast.
Additionally, each session (besides workshops) will go to Cisco Stay on-demand in just a few weeks.
You may all the time expertise interactive documentation on developer.cisco.com/studying and take a look at our Studying Labs or reserve a Sandbox to check out Cisco programmable know-how free of charge.
We’d love to listen to what you assume.
Ask a query or go away a remark beneath.
And keep related with Cisco DevNet on social!
LinkedIn | Twitter @CiscoDevNet | Fb | YouTube Channel
Share:
