API Intersection

In our latest podcast episode, we spoke with Josh Austin, Director Of Technology at InnovateMR. In late 2021, Austin completed a Brand30 30 Day Content Challenge, producing a month's worth of API-related content for the world. Austin's goal is to introduce the rest of the world, non-technical folks and business leaders alike, to the greatness of APIs. 

He shared with me two of his main takeaways from the content challenge. The first focuses on encouraging those who aren't your average developer to be as jazzed about APIs as the rest of us are and creates a little more clarity around the API space. The second piece centers around advice for API fanatics looking to create an API program of their own. 

Whether you’re a seasoned developer or a nontechnical enthusiast looking to learn more about APIs, Austin provides a wide array of content on the world of APIs that you can check out on his LinkedIn. The Stoplight API design blog also caters to many of the topics we discussed in our latest podcast with Austin.

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

In our latest podcast episode, we spoke with Keith Casey, Head of Go-to-Market and Product Strategy at Ngrok and Principal at CaseySoftware LLC. As an experienced API expert with more than twenty years of experience, Casey's on a mission now to help others create and consume amazing APIs. What sparked my interest in having Casey on the show was his recent blog post on API adoption and the pitfalls that come with it.

Casey explains how in the ideal world, users find an API, integrate it, and launch it (easy, right?). But often, API usage really follows a counter-intuitive pattern. This pattern follows three stages that Casey outlines as exploration, integration, and adoption in his piece API Adoption: The Dangerous Delay.

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

In our latest podcast episode, we spoke with Lorinda Brandon, VP of Engineering at BetterCloud. At BetterCloud, their core strength focuses on consuming APIs and interacting with various API providers. This requires an immense amount of adaptability and customization to the way her team works. Each API provider is unique in consuming APIs, processing documentation, and working alongside Developer Relations (DevRel).

We chatted with Lorinda about what it's like to be on the receiving end of developers’ API programs and the benefits and drawbacks she often sees.

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

The wave of APIs taking over the world manifests not only in new companies springing up that are absolutely reliant on APIs, but also in transforming industries that have been around for hundreds of years. For one, the entire automotive  industry is heading in the direction of being an ultimately API drive ecosystem.

In our latest podcast episode, we spoke with John Musser, the director of Data and Analytics for Ford Autonomous Vehicles  at Ford Motor Company. John was attracted to Ford because the automotive industry is undergoing massive amounts of digital transformation through connectivity, electric vehicle expansion, the introduction of self-driving cars, and more. I chatted with John about what it takes to pioneer that digital revolution and the skills needed to guide a new wave of developers through the API frontier.
 
Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

In our latest podcast episode, we spoke with T Antonio, Senior API Sales Manager at Mapbox. Previously, T's had experience as an API partnerships director and as an Enterprise Accounts & Partnerships Manager at Postman. In a change of pace for this podcast, we discussed advice on where early API companies should start when building brand recognition and developer affinity. 

We talk about the importance of API partnerships and operating on a "freemium" model when it comes to getting started in APIs.

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

In our latest podcast episode, we spoke with Jon Parise, a lead architect at Pinterest. At Pinterest, Jon provides company-wide technical leadership across several strategic initiatives and leads Pinterest's open-source program. We sat down with Jon to learn more about how the API program at Pinterest works, some keys to their success, and where they plan to go from here.

Take a listen for more on: APIs & Pinterest, navigating APIs through the constant iteration & innovation of technology, managing a giant API program at scale, and taking a design-first approach.

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

New to the Open Source World? Here's Where to Get Started: 

"My first time making an open-source pull request was actually unexpected. It was in a file upload component on Symphony, and I was using Silex. It's a smaller subset microframework based on those components. But, the problem was in a component in the Symphony repository, so I realized I had to make a request for that. I was terrified; I'd never made a pull request on an open-source piece before! I knew how to push code to GitHub at that point, but that was about it. Going through the process when you're first getting started can seem really scary, but you just have to jump in," - Erika Heidi. 

For beginner developers or those new to contributing to open source, Erika emphasizes not to overthink it. Her first time completing a pull request, she accidentally created three to four branches per request, which turned into thousands of other files. It was as if she opened a can of worms and had to navigate through it to get what she wanted accomplished. 

"I was really nervous that the contributors approving my request would be difficult to work with or that there would be barriers from a cultural standpoint since I'd never been involved in open-source work before. But, when I got the approval, I was so excited. So after that, I wasn't so scared anymore because I thought if I went through all that, I could definitely contribute more. It's been easier and easier with each pull request and open-source project I've been involved in," recalls Erika.

After getting over the "open-source hump" of her first contribution, Erika explained that it truly isn't as scary as beginner developers might think and that the entire community is filled with supportive people to learn from, grow with, and innovate alongside. 

When it comes to starting with open-source, pick a project or cause that you're passionate about. Additionally, you can seek to team up with a more experienced developer to tag-team your first open-source project contribution if you're nervous. 

"I'd say it's nice to find a project that you regularly use in your job already or that you like that's written in a language you're comfortable with because then you feel more confident about it. Working on open-source documentation is a great way to get started, too," shares Erika.  

For more ideas on where to get started, here are some open-source tools that our engineers love here at Stoplight, or check out this blog to learn how to advocate for open source at your organization. 

What to do When Working with Poor Maintainers 

"My personal experience has been good so far, and I'm grateful that I haven't witnessed any horrible experience in open source personally. But, I have occasionally seen some bad maintainers giving poor replies to other contributors that may deter a beginning developer. There was one time that one of my requests was rejected, but of course, that happens. Learn from the feedback and roll with the punches because the majority of the community is there to lift you up," - Erika Heidi. 

The most important thing to note if you stumble across a not-so-friendly open-source maintainer is to realize that not everyone in the community is like that. The best thing you can do is to clearly communicate your intentions when contributing to an open-source project at the start with the maintainers

"It's good to have some contact with the maintainers before you start and ask for more clarity or more details. A maintainer doesn't want you to lose your time or waste theirs, so it's pertinent that you have this communication going at the beginning to ensure you are on the same page," Erika said.  

Often, there is a misconception of an entire 'anonymous contributor army' behind an open-source project. However, usually, it's actually just a few other core developers solely interested in that topic or project. They likely have a vision or roadmap of where the project is headed, and it’s best to understand that before spending loads of time building a contribution that’s not congruent with the maintainers’ direction.

When you encounter a poor maintainer, don't let the naysayers get you down, keep on contributing! The more open-source projects you get involved with, the easier it becomes. When in doubt, take a step back from a project and return when you're feeling inspired. 

"I got used to working in cycles, so I'd be away for a few months, and then I would go back to a project when I am motivated. I usually go through a kind of spring, where I have an idea for the project and work for a while, then come back to it when I want to incorporate a new feature or add-on. My open-source work is meant to be a hobby," shares Erika. “However, if you have a more serious project, you should probably be more frequent. Frequency is important if you have a project that many people are involved with and depend on, and as that's a larger responsibility.” 

Open-Source Contributing is a Benefit to YOU

"There is so much freedom that exists in open source that you can go and create your own version of something if you are not satisfied with what exists. I just want to reinforce the idea of doing open source for you. Some people think that doing open source is kind of like donating something, but that's not really the case. It's a two-way street," - Erika Heidi.

In all her years of open-source experience, Erika emphasizes that if you're looking to get involved in open source, you need to do it for YOU. As I’ve said many times, “selfish” projects are often the most successful; if you don’t have a personal passion for the subject, it will be hard to maintain momentum over time. 

Open-source opportunities allow you to learn a ton as a developer, build a community, and have the chance to navigate a code that maybe you would not have had if you were just sticking to your developer day job.

To hear more about Erika's work with open source and developer relations, check out the full podcast episode on API Intersection. If you'd like to contribute to our open-source tools, here's where you can get started. 

• Prism: https://github.com/stoplightio/prism/labels/help%20wanted
• Spectral: https://github.com/stoplightio/spectral/labels/help%20wanted
• Elements: https://github.com/stoplightio/elements/labels/help%20wanted 

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

In our recent podcast episode, we spoke with Kevin Dunglas, CEO at Les-Tilleuls.coop, which is an organization made up of API experts that created the open-source framework, API Platform. Appropriately fitting into our Open-Source October theme, our conversation with Kevin included some implementation tips and a walkthrough of the benefits of API Platform and how it utilizes OpenAPI. Check out some of our biggest takeaways:

The Goal of API Platform

"The goal of API Platform is to be very easy to use so that developers can create a prototype and start working on the project quickly. And then to scale that project from there."

API Platform as an Open-Source Framework

"Using API Platform, the goal is to scale a tiny prototype to production of a deeper project without having to touch much of the code. And mostly thanks to the open-source community, we've been able to improve the framework's extensibility. It's because it's an open-source project that we are able to have this ability to do something very quickly but also to scale effectively."

Utilizing PHP in the API Platform Framework

"We hesitated when we started the project to use PHP at the time, but PHP was still very popular in France, and Symphony is still very popular as well, so we stuck with it. PHP is improving every year, and PHP 81 will have a lot of exciting new features."

Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/

In our recent podcast episode, we spoke with Tanya Vlahovic, Head of the Developer Ecosystem & Lead API Architect at eBay. As one of the first companies to heavily utilize APIs, eBay's success story is one that fascinates many in the API community. 

We sat down with Tanya to learn more about the secrets to their success, advice for those who are beginning to build an API program, and how to arm yourself with the right tools to scale. Some top themes include how good governance can feed the technical vision for APIs, nurturing a blameless culture within your organization, and bringing older APIs into modern technologies. We also talk about how you should view your APIs as products, as well as eBay's top five steps for starting an API program from scratch.

Good Governance Feeds the Technical Vision

"At eBay, we believe everything that applies to the public API should also apply to the internal private APIs, and good governance is how we do that," - Tanya Vlahovic. 

The quality of your internal microservices and private APIs directly impacts the quality of your public APIs. In her role, Tanya is responsible for taking care of the public API at eBay. Tanya emphasizes that everything that applies to the public API should also apply to the internal APIs, and having a strong technical vision can help with that. In practice, good governance can mitigate the challenges that stem from trying to follow this best practice. 

"Good organizations with a strong governance program actually create a technical vision for the API. I include crosscutting concerns, vocabulary, and consistency. Standards and patterns really help in that whole governance process. They define what is constant across the APIs, and they define the security policies," shares Tanya. 

Practicing good governance like eBay ensures that every API created should fit that technical version, and the process should be transparent and objective. 

Nurture a Blameless Culture

"We strongly believe that delivering a successful API is only possible when the teams are in power to innovate," - Tanya Vlahovic. 

eBay's API success is partly due to what Tanya calls "a blameless culture," and that culture stems beyond just DevOps. Tanya encourages her team to innovate on behalf of customers and enjoys the flexibility and risks that come with it. Fostering a blameless culture is a strategic part of eBay's foundational success so that their team members feel safe to innovate and experiment. 

"Truly connecting and communicating with the developers is vital; we pay a lot of attention to that. We partner with trusted developers, and that has worked very well for us. If you are building something for the first time, even internally, we collaborate on the internal APIs. We bring in cross-team collaboration at an early stage," shares Tanya. 

Part of fostering that blameless culture includes leaving ample room for cross-team collaboration, and the API team at eBay consists of all types of people. Their API team includes mature developers who have been with the group for over 20 years and new developers who bring various experiences and ideas to the table. eBay provides developer technical support to their developers to help them grow.

eBay also has architects in their organization who participate in all of their forums to ensure that everyone has the resources they need to succeed. Together, all these teams work with feedback groups and customer cohorts to understand what's most important in their API design. 

Then, the developer team can utilize that feedback and innovate until they get it right because they have the safe space to do so. Tanya expresses how APIs are for developers, so it's imperative that your APIs meet developer needs.

Tanya pushes her team to understand the problem statement they are trying to solve, challenge requirements, and approach every design with a healthy degree of skepticism. Their process involves a starting point of defining use cases, relevant actors, constraints, and actions that end-users may need to take with the API. 

In addition, Tanya encourages teams to think about the direction the API will evolve because the chances are that all will at some point. Her developer teams will often put placeholders for eventual extensions in the original API design to account for the future possibilities of innovation. 

Bring Older APIs into More Modern Technologies

"We started our process based on the older APIs that are heavily used that bring more value to us. We try to understand exactly how our developers leverage our APIs, how they would integrate without APIs, and how we can update them," - Tanya Vlahovic. 

Iteration is a key part of eBay's API strategy, which means constantly improving on older APIs to meet the customer needs of modern technology. When looking at which APIs to update, Tanya's team creates a vast data set of sample developers so that they can understand and calculate the value of every single developer's application. From there, they assess their API's value and the value that it brings to eBay. 

To determine the value that a particular API brings, their team relies heavily on direct feedback by collaborating with third-party developers, especially when launching additional capabilities or piloting something new. Tanya stressed that indirect feedback is equally important. The data from that feedback is the primary driver to advise their iteration strategy. 

"From the data, there are operational metrics and business metrics. These things tell us whether our platform is stable, the scale we operate, and all sorts of things. But then the business metrics are equally important because that's what can help us figure out how to grow our revenue," shares Tanya.

​​

View Your APIs​​ as Products

"We actually consider our APIs to be products, and they are first-class products at that. We have a really large and powerful ecosystem of third-party developers and applications that add value to us as well as to our buyers and sellers, which means we truly rely heavily on the developer model," - Tanya Vlahovic.

Tanya explains how they view their APIs as building blocks that developers put together in a unique way, involving all sorts of different integrations. Developers use their APIs to do a variety of things, including being managers, sellers, business owners; scaling to provide logistic services, providing bookkeeping services, handling marketing, etc. 

"We allow all developer parties to take all of these building blocks and uniquely combine them and from that create great quality experiences. We design these APIs and maintain them so that these developer groups can provide good products to their customers," shares Tanya.

Starting from Scratch, eBay's 5 Steps

"It's painful at the beginning when you're building out an API program. It isn't easy. I keep saying if you have four architects in the room by the end of the discussion, there will be at least five suggestions because at least one will change their mind before the end of the meeting," - Tanya Vlahovic...

Arnaud Lauret (the API Handyman), was featured on to API Intersection to discuss style guide best practices. As the author of the API Stylebook and the novel "Design of Web APIs," this Natixis Senior API Architect was the perfect guest for this topic. 

In our recent podcast episode, we covered the six major style guide tips that will improve your developer experience and level up your API design.  If you have a question to submit to our podcast, do it here: https://stoplight.io/question/. 

1. Not All Who Design Are Developers

"I often work with API designers who are not developers and have more of a business analyst background. So, I decided to add in specific use case documentation to better help them understand the guidelines and apply that to their API development," - Arnaud Lauret. 

Arnaud expressed how use case documentation is essential when working with API designers who don't have a developer background. The style guide focus for business-minded designers shouldn't be on the rules and rulesets, but on viewing the style guidelines as recipes. Arnaud alludes to designing APIs like shopping for a recipe and utilizing the guidelines as your shopping list to understand what components need to be designed. 

Make your style guides easy to understand and apply to the real world because not every designer that stumbles across it will have a technically-minded background.

2. The Importance of Discoverability

"What do you want to do with your APIs, and how do you want to do it? And what are the rules of your domain? Why do you name it like that? Is it? I say these things every day. If you want to be a good API design reviewer, you must not be afraid to ask stupid questions, and it's really for the better. If you don't have discoverability of your APIs, you could be in trouble," - Arnaud Lauret.

One common problem with APIs is duplication of effort. If multiple teams are developing overlapping functionality, your company may have simply wasted it’s investment, and worse, created duplication of maintenance needs going forward. 

Ensuring that new APIs are rationalized into a portfolio is essential (i.e. ensuring it makes sense, is reusable and doesn’t duplicate something that already exists). However, making sure that new designs are made available to the rest of the organization provides additional assurance that teams will connect on overlaps before investing code time. 

Furthermore, sharing leverage of APIs builds reusability and overall synergy. If consumers of APIs can’t find the right thing to use because it’s not discoverable, you might end up with another source of duplicated effort. 

3. Use Style Guide Automation to Drive Consistency 

"Teaching people to understand the concerns of consistency is necessary. At the beginning, most people don't care about it or aren't aware of it, so it needs to be addressed." - Arnaud Lauret. 

Automating style guides can quickly bring visibility to APIs which have design attributes which are inconsistent with the rest of the platform.. By eliminating (as much as possible) discussion about conventions which could be checked automatically, time is freed up to address bigger design questions than simple conventions. . Better yet, API reviews happen much faster, mitigating the risk that the API review process becomes a bottleneck to innovation.

Arnaud explains that for consistency, there are things within your style guides that you can fully automate and that which you can partially automate that will save you a lot of time later on. For example, Arnaud partially automates questions using Spectral, Stoplight's open-source linting tool that provides automatic validation and linting warnings. 

Even with automation, building consistency takes time. Arnaud explains that it's often review after review, playing the long game to slowly but surely help people understand the critical role consistency plays in developing APIs. 

4. Envision Governance from a Human Perspective 

"There are two ways to do a design review. You can be a jerk, acting as a gatekeeper and policing all the rules….or you can do it the right way by showing empathy for the designer," - Arnaud Lauret.

It's critical to employ empathy when looking at governance from a global perspective and during an API design review. We've seen this theme trending in many conversations with API leaders, clearly it’s great advice. 

When conducting an API design review, it's important not to enforce it as a method of control and job policing. As the reviewer, Arnaud notes that you need to take on the persona of a helping hand, explaining to designers that you are not there to tell them what they are doing wrong. Instead, you are there to explain design principles and provide value for how the API design can be modified or fixed. Based on the designers' context, discuss their needs and build it together. 

In the end, the API designer gets to make the final decision, as they are the domain expert. Arnaud finds this approach works exceedingly well. 

5. Apply Your Design Thinking on a Larger Scale

"The API design you are preaching and the tips you're using to create good style guides are actually principles that you can apply everywhere," - Arnaud Lauret. 

As one goes through the process of design thinking, the questions you're asking yourself and solutions you are solving can be applied everywhere, not just to style guide implementation and API design. In fact, those same principles of success can be applied to user experience in making things that are actually fulfilling, to solutions to existing programs, to mobile apps, and more. 

When developing any kind of system in general, there is a design component that people often get wrong: it has to be easy to understand. Many people will take a comprehensible system over a high-performing one any day. If you can understand how something works and how to replicate it, you're much more likely to use it and keep utilizing it in the future. 

Design thinking goes far beyond the world of APIs, but it's a great practice to apply the same concept to larger-scale programs, products, and technology teams. Digital and platform transformations often require infusing design thinking across the organization, API design is simply one facet.

6. More Resources on Creating Successful Style Guides

For more, check out our full podcast episode with Arnaud or his API Stylebook. As for other guides and resources around proper style guide creation, implementation, and API program scaling, see our list of resources below. 

• API Style Guide Best Practices 
• Style Guide Tooling 
• What to Include in Your S...