Advancing Your API Strategy in an Infrastructure World

•

0 likes•93 views

You can lead a horse to water, but you can’t make it drink. This is an accurate summary of what my initial journey of evangelizing API usage was like. In this talk I will take the audience through our journey, what worked, what didn’t work and what we learned along the way.

Technology

Advancing Your API Strategy
in an Infrastructure World
Jaap Brasser – Developer Advocate

▪ APIs?
▪ Who are we helping
▪ Open Sourcing our Efforts
▪ Closing the Loop
▪ Q&A

▪ Backup
▪ Cloud Data Management
▪ DR
▪ Test-Dev scenarios

▪ APIs are relatively new in this space
– Legacy Tooling
– GUI
▪ Lack of understanding

▪ Build from the ground up to be API-first
– We like this
▪ API endpoints classified as internal
– We do not like this
▪ OpenAPI Spec
– We definitely like this

▪ Simplify API Access
– Provide SDKs and Modules
▪ Provide Use-Cases
– Simple to implement
– Well documented
▪ Documentation
– Samples
– Quick Start Guides
– Video Tutorials

▪ Provide access to code
– GitHub
▪ Code
▪ Issues
▪ Allow to contribute
– Clear contribution guidelines
– Architectural documentation
▪ Provide contact
– Social Media
– GitHub

▪ Provide examples
– Showcase use-cases
– Showcase integrations
▪ Simplify access
– Provide web portal instead of GitHub

▪ Put API documentation on GitHub
▪ Create Quick Start guides
▪ Verified by technical writers
▪ Unexpected Contributions
▪ Created a separate portal

▪ Unified labels
▪ Standardized README.md
▪ Created Quick Start Guides
– For projects on GitHub
▪ Created video resources
▪ New Repository creation through Slack

▪ Provide clear paths to interact
– Email
– Twitter
– Slack
– GitHub
▪ Labels and organize issues
– Provides opportunity for contributions
– ‘first-timer’, ‘helpwanted’

▪ Some handholding required
– Not everyone is familiar with GitHub
– Provide content to help people onboard
▪ Active project, active contributors
– A lot of activity and contributions

My team faced several questions a year ago when we started our brand new documentation portal. - Are we going to set up a platform based on an existing solution? - Are we going to create our own platform? - Are we going to use existing internal tools like Confluence? To answer those questions we created our own process to guide our decision making: - First create a vision how your documentation should look like - Then test as many platforms as possible - Realize non are quite what you want - Realise you do not want to reinvent the wheel - Figure out how you can glue different solution together to get exactly what you want We ended up with a mix of existing technologies like Doxygen and Sphinx, glued together with custom python scripts. This allowed us to rely on proven technology and still have the flexibility to tweak the result to our requirements, getting the best of both worlds. The biggest benefit of our solution is that it uses Unit tests to ensure that the documentation and the API stay in sync and developers are forced to update documentation when they change the API. This was one of the biggest benefits we gained from our new documentation system compared to the previously used. In this talk I will go into detail how we created and implemented our process, how it worked out for us and why your team might want to follow a similar process. At the end of the talk you will have a better understanding of - How to do research and compare documentation platforms - How to perform an informed decision for their documentation needs - How not quite reinvent the wheel and get what you want.

Leaping Forward: Finding The Future of Your API Docs

Pronovix

Lessons Learned from Revamping Our Doc Site

Pronovix

Designing APIs with OpenAPI Spec

Adam Paxton

apidays LIVE Paris 2021 - Using OpenAPI to configure your API Gateway by Ole ...

apidays

Get Your Node.js API Swaggering with OpenAPI Spec

Adam Paxton

A Tour of Swagger for APIs

Allen Dean

Helps you to understand Swagger and its practical uses for representing REST APIs. You’ll learn some ways to get started. We’ll survey some of the tools and resources for describing REST APIs with Swagger. We’ll talk about what Swagger is (a specification and framework) — and isn’t (merely another doc tool). We’ll talk about the pros and cons of the Swagger-UI. And we’ll look at how Swagger helps people to learn about and explore an API.

An overview of devportal technologies and their (dis)advantages

Pronovix

It is really hard to chose the right technology to use to build your devportal. The various types of devportals support 3 authoring experiences: -CMS based authoring - tight coupling between the content model and a UI -docs as code - code repo, or file based CMS -API based authoring - command line/endpoint as the interface We will discuss how things can go wrong if you don’t cater to your different authors

This talk describes the development of ABN AMRO’s API handbook, the single-source of truth for the development and management of internal and external API products. Our company is moving towards an API-First culture and mentality. Streamlining the development process is key to enabling this. In the beginning, API development knowledge was not documented or centralized in one location. Accurate information was not available for developer teams and they were not aware of what exactly the process entailed. My colleague and I began by making agreements on how the overall process works, describing it in an intuitive way, and then by making it open and accessible company-wide. This involved setting up and hosting face-to-face meetings or MS Teams calls with specialists to find out what was required This talk describes our approach to gathering content from experts, defining and refining processes, obtaining feedback from readers, and redesigning the content in a more user-centric format.

{Re}designing a Developer Portal

Pronovix

GitHub as a Landing Page

Pronovix

API First Workflow: How could we have better API Docs through DevOps pipeline

Pronovix

API Documentation plays an important role in improving the customer’s experience with APIs, which is always a struggle for most of the company. The way to accomplish this is to transition API development culture from “Code First” to “Design First”, here in SAS we call it “API First”. For better API designing and documentation, we have built an API First CI/CD workflow which brings many open-sourced API tools together and involves developers, product managers, documentation writers, and testers to synchronously work together to develop APIs in a “Design First” approach, the industry standard. In the talk, we will discuss how the API-first Workflow could enable better collaboration between teams which could help in many aspects especially writing the openAPI documentation, keeping it up to date and sync with your code. We will take a deep look at one example, the Linting tool from API First workflow, which helps to make sure the API documentation follows the company standard from the start. With openSource linting tools like Spectral, it’s easy for teams to define their own linting rules which includes company standards. When your API specifications go through the linter in the CI/CD pipeline, the linter will throw errors and warnings as you write your spec. This will help ensure your specification is following proper guidelines and that’s all automatic.

Swagger for-your-api

Tony Tam

Swagger in the API Lifecycle

Ole Lensmar

Engineer Stunning (API) documentation

Pronovix

API Conference 2021

José Haro Peralta

API integrations can be a pain. Anyone who has worked on API integrations has probably observed that, as a general rule, no API server survives first contact with the client. Reasons vary, from badly written API documentation to complete lack of API documentation. In this presentation, I want to address this problem by showing how developers can minimize the risk of API integration failures by using an approach called documentation-driven development. In documentation-driven development, we write the API specification first using a standard specification format. I'll show how we can leverage documentation to test and validate our API implementations before we release them. I'll show how we can use tools from the current ecosystem, such as Dredd, to automatically generate tests that validate our APIs.

Automating the API Product Lifecycle

Pronovix

Looking at the full API Product Lifecycle, from defining an API and implementing the API, to launching with a solid developer site and experience, let’s see the newest tools - and potentially upcoming opportunities - to automate the creation of a solid developer experience. Creating a successful API requires a proper process from concept and design, through development, and into ongoing maintenance and responsive developer support. As developer expectations for better-quality APIs increase, tools have made it easier to implement this well. Thanks to standards like OpenAPIs, it’s easier to create a quality API, developer site, and overall experience. Many of us create API documentation or code libraries automatically from an OpenAPI spec, but there’s a lot more coming along to make our lives easier, and to make our APIs look better. In reviewing the full API Product Lifecycle to design an API people will use, let’s see the newest tools - and potentially upcoming opportunities - to better automate the creation of a compelling developer program.

A Starters Guide to Building APIs with Javascript

All Things Open

Presented by: Tom Wilson, hyper63 Presented at the All Things Open Virtual Meetup Abstract: APIs (Application Program Interfaces) is how programs can talk with other programs and is a design consideration for many products. Let’s discuss: Why you should build an application with an API? What are the top 5 requirements of designing an API with examples? Some open-source javascript frameworks that can help you design and build your API. In order to get the most out of this talk, you should have a good understanding of http REST protocol and general application development. Familiarity with javascript and technologies like NodeJS and Express would be a plus. In this talk, you should come away with a good understanding of why you should consider building an API in your application, key good practices every API should include, and how you could implement an API using Javascript.

API SDK Development – Lessons Learned

Pronovix

Building a solid API is a challenge but getting our APIs to be adopted by a larger audience, we quickly realized that having solid SDKs is the key element. At Rubrik we have been developing SDKs to supplement our APIs for over 3 years and during this process we have been making sure our SDKs provide a seamless experience for end-users to consume. When breaking API changes occur during the development of our product. The key takeaways of this session are: * How to strategize SDK development against an ever-changing API * Securely open-source your SDK development process

Implement Web API with Swagger

Jiang Wu

Case Study: Integration Automation Create Delightful API Docs

Pronovix

Swagger APIs for Humans and Robots (Gluecon)

Tony Tam

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

apidays

Understanding how to use Swagger and its tools

Swagger API

Rest API with Swagger and NodeJS

Luigi Saetta

Building APIs with Node.js and Swagger

Jeremy Whitlock

Delivering successful API integrations with documentation-driven development

José Haro Peralta

APIs are the pillars that enable communication through the web. Microservices talk to each other through APIs, and frontend applications connect to our backends through APIs. Yet, despite their importance, API integrations failures are a daily occurrence. There're many reasons why this happens, but a common denominator is the lack of API documentation, or the use of bad API documentation. In this presentation, I'll show how we can use documentation-driven development to minimise the risk of API integration failure, and I'll discuss the tools and frameworks that help us leverage the benefits of this approach. Although the risk of API integration failure can never be ruled out, the approach discussed in this presentation helps to reduce the chances of its occurrence.

Creating Interactive Docs with Postman

Pronovix

APIdays Paris 2019 - API SDK Development - Lessons Learned by Jaap Brasser, ...

apidays

OpenStack Networking: Developing and Delivering a Commercial Solution for Lo...

Radware

Why would you want to have an open source driver? Samuel Bercovici, Radware's Director of Automation & Cloud Integration, answers this and offers an introduction to Drivers in Havana in this presentation from his recent appearance at OpenStack Israel. Read more in our Press Release: http://www.radware.com/NewsEvents/PressReleases/Radware-Alteon-Provides-Load-Balancing-for-OpenStack-Cloud-Applications/

What's hot

Blood, sweat, and creating an API handbook

Pronovix

{Re}designing a Developer Portal

Pronovix

GitHub as a Landing Page

Pronovix

API First Workflow: How could we have better API Docs through DevOps pipeline

Pronovix

Swagger for-your-api

Tony Tam

Swagger in the API Lifecycle

Ole Lensmar

Engineer Stunning (API) documentation

Pronovix

API Conference 2021

José Haro Peralta

Automating the API Product Lifecycle

Pronovix

A Starters Guide to Building APIs with Javascript

All Things Open

API SDK Development – Lessons Learned

Pronovix

Implement Web API with Swagger

Jiang Wu

Case Study: Integration Automation Create Delightful API Docs

Pronovix

Swagger APIs for Humans and Robots (Gluecon)

Tony Tam

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

apidays

Understanding how to use Swagger and its tools

Swagger API

Rest API with Swagger and NodeJS

Luigi Saetta

Building APIs with Node.js and Swagger

Jeremy Whitlock

Delivering successful API integrations with documentation-driven development

José Haro Peralta

Creating Interactive Docs with Postman

Pronovix

What's hot (20)

Blood, sweat, and creating an API handbook

{Re}designing a Developer Portal

GitHub as a Landing Page

API First Workflow: How could we have better API Docs through DevOps pipeline

Swagger for-your-api

Swagger in the API Lifecycle

Engineer Stunning (API) documentation

API Conference 2021

Automating the API Product Lifecycle

A Starters Guide to Building APIs with Javascript

API SDK Development – Lessons Learned

Implement Web API with Swagger

Case Study: Integration Automation Create Delightful API Docs

Swagger APIs for Humans and Robots (Gluecon)

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

Understanding how to use Swagger and its tools

Rest API with Swagger and NodeJS

Building APIs with Node.js and Swagger

Delivering successful API integrations with documentation-driven development

Creating Interactive Docs with Postman

Similar to Advancing Your API Strategy in an Infrastructure World

APIdays Paris 2019 - API SDK Development - Lessons Learned by Jaap Brasser, ...

apidays

OpenStack Networking: Developing and Delivering a Commercial Solution for Lo...

Radware

Documentation Communities: Sound Strategy or Documentarian's Gambit?

Laura Novich

Collaborating on GitHub for Open Source Documentation

Anne Gentle

Inflectracon2020: Advantages of Integrating a DevSecOps Pipeline with the Spi...

Inflectra

Welcome to InflectraCon 2020! Please enjoy Inflectra's partner presentation on common DevSecOps pipeline concepts and the integration of a typical pipeline with the Spira family of tools. The key takeaways are: - Explore foundational DevSecOps pipeline concepts, components, and functions. - Understand how the move to DevSecOps can help detect defects before production quickly and prevent continuous bugs. - Learn how you can jump-start your efforts and have a working pipeline on your project. The presentation is by the Inflectra Partner - Coveros. The companion video is available here https://www.youtube.com/watch?v=bTQJtr1Digw

Developing Brilliant and Powerful APIs in Ruby & Python

SmartBear

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

SmartBear

The Swagger Format becomes the Open API Specification: Standardizing descript...

3scale

3D: DBT using Databricks and Delta

Databricks

Data Build Tool (DBT) is an open source technology to set up your data lake using best practices from software engineering. This SQL first technology is a great marriage between Databricks and Delta. This allows you to maintain high quality data and documentation during the entire datalake life-cycle. In this talk I’ll do an introduction into DBT, and show how we can leverage Databricks to do the actual heavy lifting. Next, I’ll present how DBT supports Delta to enable upserting using SQL. Finally, we show how we integrate DBT+Databricks into the Azure cloud. Finally we show how we emit the pipeline metrics to Azure monitor to make sure that you have observability over your pipeline.

apidays Australia 2022 - Accelerating API Engineering, Jason D'Souza & Andrew...

apidays

apidays Australia 2022 - Enabling Business Networks September 14 & 15, 2022 Accelerating API Engineering - Libraries, Templates and Governance? Jason D'Souza, Enterprise Architect - Emerging Technology at NAB Andrew Saunders, Architect - API Governance & Platforms at NAB ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

Clean Code and Common Engineering Practices

Ruth Sperer

Getting out of the monolith hell

mimmozzo_

Project Zen: Improving Apache Spark for Python Users

Databricks

Lessons learned on the Azure API Stewardship Journey.pptx

apidays

apidays LIVE Singapore 2022: Digitising at scale with APIs April 20 & 21, 2022 Lessons learned on the Azure API Stewardship Journey Adrian Hall, Principal Product Manager at Microsoft ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

Scribe online 03 scribe online cdk and api overview

Scribe Software Corp.

Practical Application of API-First in microservices development

Chavdar Baikov

Building complex applications using microservices-based architecture naturally involves a great amount of remote communication based on RESTful APIs. The REST APIs represent the contract of the microservice, with both external and internal stakeholders. Microservices, with poorly designed and unstable APIs, might pose a challenge for the whole application stack, for both adoption and maintenance. In this session, we will dig into the benefits of the API-First development approach, for designing stable, clean, and robust microservice APIs. We will showcase a practical example of how API-First development can be streamlined for developing and consuming Spring-based Java microservices, leveraging mostly free and open source technologies.

Hybrid integrationwithsap (Glenn Colpaert @ Integration Monday)

Codit

In this very hands-on session Glenn, Integration Consultant at Codit, will go through all necessary configuration steps to prepare both SAP and BizTalk to integrate with each other. Glenn will show some of the more important transactions in SAP and explain their specific function. You can expect an overview on how to leverage all the SAP functionalities to the cloud via Service Bus Relay, BizTalk Adapter Services and topping it off with a bit of Micro services.

API Workshop Amsterdam presented by API Architect Ronnie Mitra

CA API Management

This workshop with Ronnie Mitra, Layer 7's Principal API Architect, will examine the key foundational elements necessary for a solid API implementation strategy. Building great APIs is about more than just design; it requires detailed, thoughtful execution. Your API strategy needs to meet the business requirements of your organisation but it must also be flexible enough to meet your developer community’s diverse needs.

Untangling fall2017 week1

Derek Jacoby

PHP Framework Battle

Achievers Tech

Similar to Advancing Your API Strategy in an Infrastructure World (20)

APIdays Paris 2019 - API SDK Development - Lessons Learned by Jaap Brasser, ...

OpenStack Networking: Developing and Delivering a Commercial Solution for Lo...

Documentation Communities: Sound Strategy or Documentarian's Gambit?

Collaborating on GitHub for Open Source Documentation

Inflectracon2020: Advantages of Integrating a DevSecOps Pipeline with the Spi...

Developing Brilliant and Powerful APIs in Ruby & Python

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

The Swagger Format becomes the Open API Specification: Standardizing descript...

3D: DBT using Databricks and Delta

apidays Australia 2022 - Accelerating API Engineering, Jason D'Souza & Andrew...

Clean Code and Common Engineering Practices

Getting out of the monolith hell

Project Zen: Improving Apache Spark for Python Users

Lessons learned on the Azure API Stewardship Journey.pptx

Scribe online 03 scribe online cdk and api overview

Practical Application of API-First in microservices development

Hybrid integrationwithsap (Glenn Colpaert @ Integration Monday)

API Workshop Amsterdam presented by API Architect Ronnie Mitra

Untangling fall2017 week1

PHP Framework Battle

More from Pronovix

By the time they're reading the docs, it's already too late

Pronovix

Your relationship with a developer begins before they even know your product's name. In fact, before they know they need a product like yours. In this talk, Matthew will make the case that developer marketing, developer experience, and developer education are part of a continuum. And that if you're thinking of documentation as something that happens only after someone has signed-up for your API, then you're leaving it too late. He'll draw on pedagogical and marketing research to propose a model for the developer learning journey where traditional API documentation is just one stop along the way. Attend this talk and you'll come away with practical ideas for how to start educating developers earlier in their product evaluation and learning journey.

Optimizing Dev Portals with Analytics and Feedback

Pronovix

Success metrics when launching your first developer portal

Pronovix

Building our a developer portal may seem easy at the onset with off the shelf options, but when you're building a custom portal to match the needs of your company, it's not as easy. In this session, we'll talk about our process in determining the right places to start with success metrics and features through an early stage feedback back before having customers. You'll see our intention is to tell a story with multiple facets for multiple people, developers, product managers, C suite decision makers etc... Stories around API usage, health, cost, errors and support to provide our users with an overall of their business performance through our APIs.

Documentation, APIs & AI

Pronovix

AI is entering the world of APIs, where API documentation plays a critical role. One of the fundamental challenges is the need to share understanding about an API and keep the knowledge up to date. AI can potentially speed up API integrations dramatically, but it greatly depends on API documentation. Let's explore the emerging approach to employing AI in APIs, discuss its impact on API documentation, and see how changing our way of working with APIs will lead to self-integrating applications.

Making sense of analytics for documentation pages

Pronovix

As content producers, we invest considerable time and effort in developing, packaging, and delivering content that we think our users need. After publishing the content, we hope that users find our content useful. And we often wonder how users really navigate and consume our content. Web page analytics can help us gauge the information needs of our customers, assess their content consumption behavior, and find opportunities to improve our content and how we deliver it. Kumar explores the basics of web analytics, pitfalls of relying too much on web analytics for important decisions, the typical web analytics process, and he will share some guidelines for interpreting web analytics numbers.

Feedback cycles and their role in improving overall developer experiences

Pronovix

Drawing from experiences from open source work and her time at Spotify, Serah’s talk cover the challenges, opportunities and hacks around proactive and reactive monitoring, processing, tracking and acting on stakeholder and community feedback, and argue for the centricity of well-defined feedback loops in improving the overall developer experiences for any product and features you are responsible for.

GraphQL Isn't An Excuse To Stop Writing Docs

Pronovix

The main goal of API documentation is to help developers understand how to use an API. With GraphQL, developers often assume it's self-documenting capabilities are sufficient for anyone that consumes their GraphQL API. But did you ever validate this? Good API documentation offers both static and interactive ways to learn how to consume the API. API's that support GraphQL often only come with interactive documentation, in the shape of a GraphiQL Playground. However, the first time you (or your users) use a GraphQL API can be very frustrating as GraphQL APIs typically only have an interactive playground. it increases the complexity for newcomers to GraphQL as it assumes you’re already familiar with GraphQL. But with GraphQL, you’re not limited to just an interactive playground, as you can create static or interactive documentation next to having this playground. This talk explores which forms of documentation you can use and how they add value to your GraphQL API.

API Documentation For Web3

Pronovix

Web3 is one of the fastest-growing spaces on the web right now, with thousands of new projects emerging every week. Each project aims to fill a gap in the space by providing a new technology How do we keep up with documentation, and what should be prioritized for these projects as they scale? Web3, also referred to as the read-write-own web, is a new form of the internet that utilizes technologies such as blockchain networks, cryptocurrency, crypto wallets, and digital assets like NFTs. The Web3 space is growing by the thousands every week, with new projects and technologies constantly emerging. As writers, it can be challenging to navigate through the space, make sense of every piece of new content, and understand what should be written about for others to read, and what will be irrelevant next week. Many of these new technologies are using pieces of code known as smart contracts or interacting with the APIs of multiple applications at once. What documentation are end-users looking for, and what is the most beneficial format for them to read and comprehend all of this new information? In this talk, I'll discuss what I've learned as a Senior Technical Writer for Filebase, a decentralized cloud storage provider at the heart of hundreds of Web3 projects, and what our customers have benefited from the most when it comes to documentation.

Why your API doesn’t solve my problem: A use case-driven API design

Pronovix

API docs frequently fail to address developers’ needs by omitting common usage scenarios and use cases. Let’s take a look at good and bad practices for documenting API use cases, and take steps to ensure that developers get from our API and docs what they really want. You wrote an API specification, documented your endpoints, and published SDKs. Here’s a question, though: Does your API actually solve your users’ problems? API providers often fail to address common use cases to solve users’ needs, or their assumptions don’t match the reality. This may end up in frustration and loss of users. In this talk, we will take a peek into developers’ mindset. I will show how to better understand the developers’ needs by researching the usage patterns, existing libraries and 3rd party experience layers, provide examples of good and bad practices, and suggest actionable steps to improve developer experience for your API.

unREST among the docs

Pronovix

Developing a best-in-class deprecation policy for your APIs

Pronovix

Nobody likes ambiguity—especially when it comes to the stability of APIs and the expectations for availability long term. Avoid common pitfalls and explore a critical area where trust is built with developers through thoughtful policy and the development of best-in-class documentation. A good deprecation policy involves a lot of forward thinking and an awareness of how developers or end users are currently leveraging your capabilities, and how a given API or feature deprecation could affect them in the future. The hard-earned trust that you’ve built and maintained with these individuals is at risk with any type of policy or documentation that is unclear. The road to developing a clear, trustworthy deprecation policy is a multi-faceted initiative with input from product, engineering, customer success and other cross-functional teams, as well as external market awareness. Knowing which voices to have in the room, what the industry standards are, and formulating appropriate communication timelines will ensure a world class policy is developed and documented before it’s needed. Join us as we dive into the nuances of this process and how to avoid the common pitfalls that come from lacking a strategic, thoughtful approach to documenting a deprecation policy for your APIs.

Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone

Pronovix

At MongoDB, we now generate REST API references for MongoDB Atlas from annotations in the product’s source. Our team’s writers proposed, planned, led, and implemented this project–and learned a lot along the way. We’ll share how we got buy-in from engineering and product stakeholders, coordinated the project across teams, implemented swagger-core annotations in Java, and drove positive change to benefit our team, the company, and our users.

What do developers do when it comes to understanding and using APIs?

Pronovix

It turns out there is no single answer. Developers may have unique goals, motivations, constraints, and challenges, and all of these influence how they approach the problem in front of them. However, more than a decade ago, three development styles were identified - systematic, pragmatic, and opportunistic - and the academic literature suggests that these still exist today. Two of the three approaches, the systematic and the opportunistic pattern, can be considered as opposite extremes, while the pragmatic approach is situated in between and is similar to both. It is not a personality trait - people may approach a situation one way or another depending on their circumstances, goals, and motivations (however, they may also have a preferred approach, which is usually their characteristic). Understanding the differences between these patterns (and the different needs) helps us to design in a way that serves most of the users, and even helps them to get into a state of flow by providing the optimal level of challenge to solve their problem.

Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations

Pronovix

It's time to take the bias out of code, UI, docs, configurations, or our everyday language by ensuring we choose our words carefully to avoid harmful subtext or exclusion. We can do our part and take steps by examining assets from code to config files to API specifications to standards. Heard of suss? You can suss out more information or you can find someone's information to be suss. "Suss" shows the flexibility of language. It’s an ongoing process to change how we use certain words. It's important to choose words carefully to convey the correct meaning and avoid harmful subtext or exclusion. Let's explore some of the tools and triage methods that it takes from an engineering viewpoint to make bias-free choices. How can you ensure that biased words do not sneak into code, UI, docs, configurations, or our everyday language? First, let's walk through how to take an inventory of assets from code to config files to API specifications to standards. Next, by placing those findings into categories, prioritize the work to substitute with inclusive alternatives. Let's examine some examples using both API and code assets. Next is a demonstration of how to automate analyzing your source code or documentation with a linter, looking for patterns based on rules that are fed into the tool. What's in the future for these efforts? Inclusive language should expand beyond English and North America efforts. To do so, let's organize the work with automation tooling, as engineers do.

Creating API documentation for international communities

Pronovix

How to create documentation and write code for an international audience, not just the people who speak and think like you. Make your APIs more useful for everyone on the planet. Much of the documentation supplied by both Open Source and Close Souce projects assume the community have a good understanding of the English language and often North American culture as well. This creates barriers for many solution providers, who are the gateway to potentially huge markets for your project. This talk discusses some of the cultural differences, particularly for people from Asia, in using English language API documentation. It suggests some strategies to help diverse audiences understand you APIs and create solutions using them. The talk will cover not only differences in language but also other cultural differences that are often not obvious. For example: Different expectations about publication formats, release processes, levels of support during the development process Meeting and communications styles Software development workflows, processes, and tools Supporting people who are visually impaired will also be briefly discussed. As well as discussing these issues, specific suggestions will be provided to make API docs accessible for as many people as possible. This talk is based on Alec's work with customers in Europe, North America, Middle East, Asia, and Australasia. The last five have been spent as a developer evangelist working with PaperCut partners in China, Japan, Korea, US and Europe.

One Developer Portal to Document Them All

Pronovix

APIs in a modern enterprise are rarely uniform or all of the same type. The multitude of API types can be due to organic growth, mergers and acquisitions, or any number of other reasons. Regardless of their origin, APIs of all types need to be fully documented to facilitate a developer’s journey as they interact with your API ecosystem in order to develop useful applications. In this talk I will show examples of how we have augmented developer portals to document APIs that are not of the REST variety, such as AsyncAPI, GraphQL, SOAP, gRPC, and more, such that all API documentation can seamlessly live side-by-side.

Docs-as-Code: Evolving the API Documentation Experience

Pronovix

We are a software engineering team creating API docs. Docs are authored using Instructional Design principles to narrate use-cases and practical API implementations. This talk shares why & how we've applied software development practices to evolve our document tooling, creation, & delivery methods. Our APIs describe asynchronous protocols used for embedded software (firmware) components in a digital 2-way radio communications system. The API is protocol data unit (PDU) based and its definition is described in a proprietary format; consequently, well-known API formats, such as Swagger/OpenAPI, or tools, such as doxygen, are not used. Our product training and technical writing teams are very experienced in Instructional Design methods, but these teams have only written documentation for an end-user audience. Understanding software development processes is equally important as understanding two-way radio networks in order to successfully integrate with the APIs. This is the rationale for having a software engineering team develop the skillsets to write API documentation for a developer audience. With a solid foundation of API documentation in place, regular examination of engineering efficiency and developer experience is appropriate. Repeated actions can be replaced by automation. Content can be modular and re-usable. Formats can be streamlined for easier consumption. Docs can be made portable and lightweight for faster delivery.

Developer journey - make it easy for devs to love your product

Pronovix

Ever wonder how some products are just lovable and easy to use while other are not? The good products have optimized onboarding into their ecosystem where you get the information served at the right time. That’s thanks to developer journey and we will teach you how to get it right! We will go through the basics such as how to analyze existing and non-existing developer touchpoints, set metrics and optimize them to increase the conversion.

Complexity is not complicatedness

Pronovix

Deliberate Complexity Conferences - 19 JULY 2022 Alicia Juarrero - Complexity is not complicatedness Professor Alicia Juarrero, a leading complexity theory philosopher and academic, as well as the founder and president of VectorAnalytica, a technology company that specializes in large scale scientific data capture and real time analysis tools. Alicia's work in complexity theory is widely quoted by thought leaders in the technology space and referenced in many recent complexity-informed approaches for managing highly dynamic systems, as well as in knowledge management.

How cognitive biases and ranking can foster an ineffective architecture and d...

Pronovix

More from Pronovix (20)

By the time they're reading the docs, it's already too late

Optimizing Dev Portals with Analytics and Feedback

Success metrics when launching your first developer portal

Documentation, APIs & AI

Making sense of analytics for documentation pages

Feedback cycles and their role in improving overall developer experiences

GraphQL Isn't An Excuse To Stop Writing Docs

API Documentation For Web3

Why your API doesn’t solve my problem: A use case-driven API design

unREST among the docs

Developing a best-in-class deprecation policy for your APIs

Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone

What do developers do when it comes to understanding and using APIs?

Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations

Creating API documentation for international communities

One Developer Portal to Document Them All

Docs-as-Code: Evolving the API Documentation Experience

Developer journey - make it easy for devs to love your product

Complexity is not complicatedness

How cognitive biases and ranking can foster an ineffective architecture and d...

Recently uploaded

Smart TV Buyer Insights Survey 2024 by 91mobiles.pdf

91mobiles

ODC, Data Fabric and Architecture User Group

CatarinaPereira64715

Key Trends Shaping the Future of Infrastructure.pdf

Cheryl Hung

Bits & Pixels using AI for Good.........

Alison B. Lowndes

The Art of the Pitch: WordPress Relationships and Sales

Laura Byrne

Clients don’t know what they don’t know. What web solutions are right for them? How does WordPress come into the picture? How do you make sure you understand scope and timeline? What do you do if sometime changes? All these questions and more will be explored as we talk about matching clients’ needs with what your agency offers without pulling teeth or pulling your hair out. Practical tips, and strategies for successful relationship building that leads to closing the deal.

From Daily Decisions to Bottom Line: Connecting Product Work to Revenue by VP...

Product School

State of ICS and IoT Cyber Threat Landscape Report 2024 preview

Prayukth K V

The IoT and OT threat landscape report has been prepared by the Threat Research Team at Sectrio using data from Sectrio, cyber threat intelligence farming facilities spread across over 85 cities around the world. In addition, Sectrio also runs AI-based advanced threat and payload engagement facilities that serve as sinks to attract and engage sophisticated threat actors, and newer malware including new variants and latent threats that are at an earlier stage of development. The latest edition of the OT/ICS and IoT security Threat Landscape Report 2024 also covers: State of global ICS asset and network exposure Sectoral targets and attacks as well as the cost of ransom Global APT activity, AI usage, actor and tactic profiles, and implications Rise in volumes of AI-powered cyberattacks Major cyber events in 2024 Malware and malicious payload trends Cyberattack types and targets Vulnerability exploit attempts on CVEs Attacks on counties – USA Expansion of bot farms – how, where, and why In-depth analysis of the cyber threat landscape across North America, South America, Europe, APAC, and the Middle East Why are attacks on smart factories rising? Cyber risk predictions Axis of attacks – Europe Systemic attacks in the Middle East Download the full report from here: https://sectrio.com/resources/ot-threat-landscape-reports/sectrio-releases-ot-ics-and-iot-security-threat-landscape-report-2024/

Accelerate your Kubernetes clusters with Varnish Caching

Thijs Feryn

Le nuove frontiere dell'AI nell'RPA con UiPath Autopilot™

UiPathCommunity

In questo evento online gratuito, organizzato dalla Community Italiana di UiPath, potrai esplorare le nuove funzionalità di Autopilot, il tool che integra l'Intelligenza Artificiale nei processi di sviluppo e utilizzo delle Automazioni. 📕 Vedremo insieme alcuni esempi dell'utilizzo di Autopilot in diversi tool della Suite UiPath: Autopilot per Studio Web Autopilot per Studio Autopilot per Apps Clipboard AI GenAI applicata alla Document Understanding 👨‍🏫👨‍💻 Speakers: Stefano Negro, UiPath MVPx3, RPA Tech Lead @ BSP Consultant Flavio Martinelli, UiPath MVP 2023, Technical Account Manager @UiPath Andrei Tasca, RPA Solutions Team Lead @NTT Data

To Graph or Not to Graph Knowledge Graph Architectures and LLMs

Paul Groth

КАТЕРИНА АБЗЯТОВА «Ефективне планування тестування ключові аспекти та практ...

QADay

JMeter webinar - integration with InfluxDB and Grafana

RTTS

Watch this recorded webinar about real-time monitoring of application performance. See how to integrate Apache JMeter, the open-source leader in performance testing, with InfluxDB, the open-source time-series database, and Grafana, the open-source analytics and visualization application. In this webinar, we will review the benefits of leveraging InfluxDB and Grafana when executing load tests and demonstrate how these tools are used to visualize performance metrics. Length: 30 minutes Session Overview ------------------------------------------- During this webinar, we will cover the following topics while demonstrating the integrations of JMeter, InfluxDB and Grafana: - What out-of-the-box solutions are available for real-time monitoring JMeter tests? - What are the benefits of integrating InfluxDB and Grafana into the load testing stack? - Which features are provided by Grafana? - Demonstration of InfluxDB and Grafana using a practice web application To view the webinar recording, go to: https://www.rttsweb.com/jmeter-integration-webinar

Unsubscribed: Combat Subscription Fatigue With a Membership Mentality by Head...

Product School

Assuring Contact Center Experiences for Your Customers With ThousandEyes

ThousandEyes

Software Delivery At the Speed of AI: Inflectra Invests In AI-Powered Quality

Inflectra

In this insightful webinar, Inflectra explores how artificial intelligence (AI) is transforming software development and testing. Discover how AI-powered tools are revolutionizing every stage of the software development lifecycle (SDLC), from design and prototyping to testing, deployment, and monitoring. Learn about: • The Future of Testing: How AI is shifting testing towards verification, analysis, and higher-level skills, while reducing repetitive tasks. • Test Automation: How AI-powered test case generation, optimization, and self-healing tests are making testing more efficient and effective. • Visual Testing: Explore the emerging capabilities of AI in visual testing and how it's set to revolutionize UI verification. • Inflectra's AI Solutions: See demonstrations of Inflectra's cutting-edge AI tools like the ChatGPT plugin and Azure Open AI platform, designed to streamline your testing process. Whether you're a developer, tester, or QA professional, this webinar will give you valuable insights into how AI is shaping the future of software delivery.

Knowledge engineering: from people to machines and back

Elena Simperl

Essentials of Automations: Optimizing FME Workflows with Parameters

Safe Software

Are you looking to streamline your workflows and boost your projects’ efficiency? Do you find yourself searching for ways to add flexibility and control over your FME workflows? If so, you’re in the right place. Join us for an insightful dive into the world of FME parameters, a critical element in optimizing workflow efficiency. This webinar marks the beginning of our three-part “Essentials of Automation” series. This first webinar is designed to equip you with the knowledge and skills to utilize parameters effectively: enhancing the flexibility, maintainability, and user control of your FME projects. Here’s what you’ll gain: - Essentials of FME Parameters: Understand the pivotal role of parameters, including Reader/Writer, Transformer, User, and FME Flow categories. Discover how they are the key to unlocking automation and optimization within your workflows. - Practical Applications in FME Form: Delve into key user parameter types including choice, connections, and file URLs. Allow users to control how a workflow runs, making your workflows more reusable. Learn to import values and deliver the best user experience for your workflows while enhancing accuracy. - Optimization Strategies in FME Flow: Explore the creation and strategic deployment of parameters in FME Flow, including the use of deployment and geometry parameters, to maximize workflow efficiency. - Pro Tips for Success: Gain insights on parameterizing connections and leveraging new features like Conditional Visibility for clarity and simplicity. We’ll wrap up with a glimpse into future webinars, followed by a Q&A session to address your specific questions surrounding this topic. Don’t miss this opportunity to elevate your FME expertise and drive your projects to new heights of efficiency.

AI for Every Business: Unlocking Your Product's Universal Potential by VP of ...

Product School

PHP Frameworks: I want to break free (IPC Berlin 2024)

Ralf Eggert

In this presentation, we examine the challenges and limitations of relying too heavily on PHP frameworks in web development. We discuss the history of PHP and its frameworks to understand how this dependence has evolved. The focus will be on providing concrete tips and strategies to reduce reliance on these frameworks, based on real-world examples and practical considerations. The goal is to equip developers with the skills and knowledge to create more flexible and future-proof web applications. We'll explore the importance of maintaining autonomy in a rapidly changing tech landscape and how to make informed decisions in PHP development. This talk is aimed at encouraging a more independent approach to using PHP frameworks, moving towards a more flexible and future-proof approach to PHP development.

Dev Dives: Train smarter, not harder – active learning and UiPath LLMs for do...

UiPathCommunity

💥 Speed, accuracy, and scaling – discover the superpowers of GenAI in action with UiPath Document Understanding and Communications Mining™: See how to accelerate model training and optimize model performance with active learning Learn about the latest enhancements to out-of-the-box document processing – with little to no training required Get an exclusive demo of the new family of UiPath LLMs – GenAI models specialized for processing different types of documents and messages This is a hands-on session specifically designed for automation developers and AI enthusiasts seeking to enhance their knowledge in leveraging the latest intelligent document processing capabilities offered by UiPath. Speakers: 👨‍🏫 Andras Palfi, Senior Product Manager, UiPath 👩‍🏫 Lenka Dulovicova, Product Program Manager, UiPath

Recently uploaded (20)

Smart TV Buyer Insights Survey 2024 by 91mobiles.pdf

ODC, Data Fabric and Architecture User Group

Key Trends Shaping the Future of Infrastructure.pdf

Bits & Pixels using AI for Good.........

The Art of the Pitch: WordPress Relationships and Sales

From Daily Decisions to Bottom Line: Connecting Product Work to Revenue by VP...

State of ICS and IoT Cyber Threat Landscape Report 2024 preview

Accelerate your Kubernetes clusters with Varnish Caching

Le nuove frontiere dell'AI nell'RPA con UiPath Autopilot™

To Graph or Not to Graph Knowledge Graph Architectures and LLMs

КАТЕРИНА АБЗЯТОВА «Ефективне планування тестування ключові аспекти та практ...

JMeter webinar - integration with InfluxDB and Grafana

Unsubscribed: Combat Subscription Fatigue With a Membership Mentality by Head...

Assuring Contact Center Experiences for Your Customers With ThousandEyes

Software Delivery At the Speed of AI: Inflectra Invests In AI-Powered Quality

Knowledge engineering: from people to machines and back

Essentials of Automations: Optimizing FME Workflows with Parameters

AI for Every Business: Unlocking Your Product's Universal Potential by VP of ...

PHP Frameworks: I want to break free (IPC Berlin 2024)

Dev Dives: Train smarter, not harder – active learning and UiPath LLMs for do...

Advancing Your API Strategy in an Infrastructure World

1. Advancing Your API Strategy in an Infrastructure World Jaap Brasser – Developer Advocate

4. ▪ APIs? ▪ Who are we helping ▪ Open Sourcing our Efforts ▪ Closing the Loop ▪ Q&A

5. APIs?

6. ▪ Backup ▪ Cloud Data Management ▪ DR ▪ Test-Dev scenarios

7. ▪ APIs are relatively new in this space – Legacy Tooling – GUI ▪ Lack of understanding

8. ▪ Build from the ground up to be API-first – We like this ▪ API endpoints classified as internal – We do not like this ▪ OpenAPI Spec – We definitely like this

9. Who are we helping

10.

11. Different roles

12. ▪ Simplify API Access – Provide SDKs and Modules ▪ Provide Use-Cases – Simple to implement – Well documented ▪ Documentation – Samples – Quick Start Guides – Video Tutorials

13. ▪ Provide access to code – GitHub ▪ Code ▪ Issues ▪ Allow to contribute – Clear contribution guidelines – Architectural documentation ▪ Provide contact – Social Media – GitHub

14. ▪ Provide examples – Showcase use-cases – Showcase integrations ▪ Simplify access – Provide web portal instead of GitHub

15. Open Sourcing our Efforts

16. ▪ Put API documentation on GitHub ▪ Create Quick Start guides ▪ Verified by technical writers ▪ Unexpected Contributions ▪ Created a separate portal

17. ▪ Unified labels ▪ Standardized README.md ▪ Created Quick Start Guides – For projects on GitHub ▪ Created video resources ▪ New Repository creation through Slack

18. Closing the loop

19. ▪ Provide clear paths to interact – Email – Twitter – Slack – GitHub ▪ Labels and organize issues – Provides opportunity for contributions – ‘first-timer’, ‘helpwanted’

20. ▪ Some handholding required – Not everyone is familiar with GitHub – Provide content to help people onboard ▪ Active project, active contributors – A lot of activity and contributions

21.

22. jaap_brasser

Advancing Your API Strategy in an Infrastructure World

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Advancing Your API Strategy in an Infrastructure World

Similar to Advancing Your API Strategy in an Infrastructure World (20)

More from Pronovix

More from Pronovix (20)

Recently uploaded

Recently uploaded (20)

Advancing Your API Strategy in an Infrastructure World