Find here all the things to know about Bump.sh, API ecosystem and tech in general.
Docs as code is a powerful methodology that aligns documentation processes with software development workflows. It treats documentation as a first-class citizen in the development lifecycle by applying a similar approach to the standard development process. Let’s explore what it is, how it works, and how you can get started.
Keep reading
API governance is critical for ensuring consistency, security, and quality in enterprise API programs. However, maintaining governance across a distributed organization can be challenging, especially as teams grow and APIs proliferate. In some cases, organizations opt to define guidelines rather than API governance in an attempt to reduce the work required day-to-day.
Keep reading
When I started as a Product Manager, I felt like a great integration between SaaS products would involve some UI elements. Something like buttons with the other tool's logo on it. Then I realized the importance of "APIs" behind the scene, whether there would be a button or not.
Keep reading
APIs are at the core of modern enterprise architectures, powering integrations, automation, and digital products. Yet, API sprawl remains a persistent challenge—APIs are often scattered across different teams, tools, and repositories, making discovery and governance difficult.
Keep reading
API Design-First, also known as "schema-first" or "contract-first", is all about designing the interface of an API before writing any code. It's about planning the API contract first, and defining what the API does and how it works so everyone's on the same page before implementation starts. This approach has been around for a while, and over time, it's evolved to meet the needs of different technologies. These days, OpenAPI has become the defacto standard for designing REST APIs, and AsyncAPI has become the defacto standard for describing event-driven APIs. This workflow can make life easier for everyone the whole way through the lifecycle of an API.
Keep reading
At Bump.sh, we’re excited to announce a new feature we have been developing: The API Explorer, a web-based UI designed to help users send HTTP requests to documented APIs directly from their browser. While this tool offers enhanced usability, it also posed several unique challenges, especially around ensuring user privacy and compliance with CORS (Cross-Origin Resource Sharing) restrictions. This blog post takes a look at our approach and how we ended up creating an open-source proxy solution called cors-toujours.
Keep reading
Partner APIs are far more common than public-facing APIs. Yet, inaccessible documentation for these APIs is often a big barrier to partner success. In fact, nearly 40% of developers say inconsistent docs are their biggest roadblock when it comes to API integration, found the 2024 State of the API Report. Pain points around API documentation can cause miscommunications, errors, and time delays.
Keep reading
Gathering user feedback is essential to improving your API and ensuring it meets users' needs. With Bump.sh, you can integrate feedback forms directly into your OpenAPI documentation by embedding a link to a form using x-feedbackLink extension (/help/publish-documentation/feedback/).
Keep reading
If you’ve worked with OpenAPI v3.x, you might have come across the discriminator field in schemas. It’s often used alongside oneOf, anyOf, or allOf when you’ve got different variations of a type—polymorphism, essentially. At first glance, it seems pretty handy; it’s meant to help you figure out which specific schema to use when certain values are present, but JSON Schema can handle this out of the box without using the poorly supported OpenAPI-only keyword discriminator.
Keep reading
You are building an API for a reason. You need to integrate with another business to make money. You need to get data to a new frontend application to get more users to make money. You have important business to do, so why should you waste time creating API documentation?
Keep reading
There have been a number of options emerge recently beyond OpenAPI for documenting your API interface details. One such option is TypeSpec, which offers a declarative syntax to define HTTP, REST, and gRPC-based APIs. The high-level syntax allows developers to define API types, schemas, and interfaces, making it easier to manage the complexities of modern API ecosystems.
Keep reading
Although public APIs like Stripe, Notion, or Twilio tend to get the spotlight, there's a hidden, deep potential in partner APIs. Opening APIs to select partners can enable collaboration and new revenue streams. But, not all technical leaders, let alone executives, truly realize the benefits a partner API strategy unlocks.
Keep reading
Composing an OpenAPI document can be daunting, especially during the early stages of API design. Your API design will need to evolve as you learn more about the problem space. To avoid needing to re-write large portions of your OpenAPI document, I recommend a phased approach to designing and documenting your API. The process starts with a breadth-first approach, capturing the essentials of the API including purpose and scope, then adding high-level operational descriptions. Finally, add more detail as you gain insights and receive feedback, until your OpenAPI document is complete.
Keep reading
Arazzo is a new specification from the OpenAPI Initiative for describing and documenting complex workflows throughout your API which touch multiple operations (a.k.a endpoints). The word “arazzo” means “tapestry” in Italian, which gives you a bit of an idea what it’s about, but let’s let the spec do the talking:
Keep reading
API management has grown over the last decade. From cloud to independent APIM vendors, organizations have a variety of options for managing, monitoring, and securing their APIs. In many cases, organizations have more than one APIM vendor. This multitude of choices, while beneficial, also introduces complexity, particularly when it comes to the integration and management of developer portals.
Keep reading
Developer experience (DX) is a critical element of any API product. A well-designed and intuitive API not only attracts developers but also empowers them to build innovative applications and integrations. In some cases, organizations may have a large number of APIs that address the needs of multiple audiences. This article explores how API product bundling, a strategic approach to packaging APIs, can significantly enhance DX.
Keep reading
Recently we published a guide showing how Bump.sh users can migrate their OpenAPI descriptions out of SwaggerHub and into Bump.sh, and I thought it would be helpful to spend a bit of time writing about why you'd want to do that. The migration guide shows how, but let’s talk about why freeing your API descriptions from a walled garden is important, and what can be done when your API design workflow is entirely under your own control.
Keep reading
For many organizations, an API style guide is a well-established document. It outlines the conventions and patterns that developers should follow when building APIs. These guides typically cover topics like naming conventions for resources and parameters, request and response structures, and error handling. However, a crucial element often is missing: API documentation guidelines.
Keep reading
APIs are not static, as new operations are added and existing operations are improved as API usage grows. As customer and business needs evolve, APIs need to adapt as well. This often leads to the inevitable process of API deprecation – the gradual phasing out of an old API in favor of a newer, improved version.
Keep reading
Technical writers are often challenged with keeping API documentation in sync with an ever-evolving API design. This article explores the challenges and solutions for tackling this ongoing struggle, focusing on parallel development and leveraging automation to streamline the process.
Keep reading
You've built a brilliant API, and you've taken the time to document it, but how do you get this API advertised to potential users? After all, the more users that discover your API, the more business you're getting, so it's worth thinking about discoverability beyond a tweet and a blog.
Keep reading
A common pitfall of API documentation is focusing solely on documenting individual operations in isolation, neglecting the complexity of real-world workflows that involve chaining multiple operations together. While individual API operations often appear well-designed, the true test lies in how users can orchestrate these operations to achieve specific goals. This can lead to confusion and frustration for developers, hindering API adoption and ultimately compromising its effectiveness.
Keep reading
The OpenAPI schema component offers API designers and technical writers an opportunity to define the structure of an API's resource representation structure and is a primary reference point for both internal developers and external consumers. Improving documentation in this area can significantly enhance usability and reduce integration times, errors, and frustration. In this article, we will explore tips and examples on how to effectively document schema components in OpenAPI specification documents.
Keep reading
OpenAPI (OAS) specifications play a crucial role in API development, serving as the foundation for clear communication between developers and consumers. While technical details within the specification are essential, the info section often gets overlooked, leading to a missed opportunity to provide valuable context and understanding.
Keep reading
After conducting API design and documentation reviews for over a decade, there are common mistakes that most developers make when composing their reference documentation using the OpenAPI Specification. Let’s look at five operation-specific improvements that you can make to deliver on a great developer experience while reducing the support costs of your API.
Keep reading
Until recently, technical writers focused on delivering manuals for software, often in PDF or HTML format. These manuals consisted of step-by-step guidance for using software, often accompanied by annotated screenshots. The technical writer was critical for ensuring end users were able to use the software effectively and efficiently while reducing the vendor’s support costs.
Keep reading
Your API is nearing completion and it’s time to let the world know about it. This means that it is time to complete your API documentation effort. But, where should you start? How do you know if you covered everything that your decision makers and developers will need to select your API and get started successfully?
Keep reading
A few years ago most API designers, developers, and technical writers would have had very little reason to bump into JSONPath, but its starting to get more and more relevant as more tools and standards start relying on it. So what is JSONPath, what is it used for, and how can you get up to speed with using it?
Keep reading
When you think of API documentation, what comes to mind? More than likely, you think of reference documentation that describes how to use an API, including the operations and request/response details. This kind of reference documentation leverages the OpenAPI Specification (formerly known as Swagger). However, there is more to documenting your API than just the reference documentation. Let’s explore the different types of API documentation and the role each has to play in helping a developer become proficient in consuming your API.
Keep reading
The Bump.sh team has been busy adding brilliant features to the hosted service and their command-line tools, and whilst they’ve been doing that I’ve been typing up infinite guides helping people learn how to get OpenAPI out of (or into!) their various programming languages and web frameworks.
Keep reading
Everyone working with OpenAPI (formerly Swagger) will have come across the PetStore at some point. It's a sample OpenAPI description for an imaginary Pet Store with an API, but the OpenAPI is old, and the API it describes is pretty far from best practices. We thought it was time for a refresh, so we're bringing you the Train Travel API, a new sample OpenAPI you can use for your tooling and testing.
Keep reading
It's a situation that slowly creeps up on you, gradually leading to a harsh realization. A realization that calls for drastic measures. An information you're missing and you seek it at its source. A question asked by a user, making you think "it would be nice to write it down somewhere." An explanation you can't find anywhere. Or maybe not where you'd like it. Or not quite in its entirety.
Keep reading
The excellent Phil Sturgeon, API expert and reforester, is a well known OpenAPI evangelist since years. And since a few months, we're super proud to work with him, building a new knowledge base that supports API builders in their daily jobs. Discover our guides and tutorials, whether you're new or advanced at building APIs, whether they're REST or Event-driven.
Keep reading
API Code-first is the art of building an API, and then popping some annotations or metadata in there to output API documentation in an API description format like OpenAPI. There are a few conceptually different ways to do this, with new tools popping up to help make everything easier, so this guide will show you how those different types of tool work.
Keep reading
After using OpenAPI or AsyncAPI for a while, you might notice your description documents have become a rather unwieldy mess of YAML and JSON. You end up with a whole lot of repetition, and this huge mess just loves to trigger merge conflicts as multiple developers change different things but Git seems none the wiser.
Keep reading
Depending on how your application is designed and what it needs to accomplish, you probably want to consider choosing one type of communication protocol for your API over another—namely, synchronous or asynchronous. And which protocol you use determines which specification you need to follow for your API—OpenAPI or AsyncAPI.
Keep reading
Express is a popular backend JavaScript framework for building landing pages and integrated content management systems or integrating APIs with other tools. With over twenty million weekly downloads on npm at the time of writing, the framework's popularity comes from its ease of setup and use, extensibility with first- and third-party middleware functions, and its flexible built-in router.
Keep reading
Ever since a certain pandemic, remote work has become increasingly popular. It was enforced by lockdowns, adopted long-term by some teams, and criticized for allegedly hampering productivity. Lately, some companies have been reversing their approval of remote work. On the other hand, entire teams are advocating for it to become the norm.
Keep reading
Architecture diagrams are essential in the API development process. They provide a map of how different systems interact to help software teams manage and maintain them, and they provide insight into the architect’s vision for the entire system. Along with other elements like interactive API portals, API architecture diagrams also help enrich your API’s documentation.
Keep reading
API-first design is a software development approach built around the idea that the application programming interfaces (APIs) should be the primary focus of the development process, with other system components, such as the user interface (UI) being developed later.
Keep reading
In software engineering, dev teams often dismiss documentation as tangential—secondary to product development and feature work. While code design and implementation is a top priority for most software engineers, creating good documentation should carry equal weight in the product development process.
Keep reading
Who would have thought that breaking the payment API of the company I was working for at the time would lead me to write this post a few years later? Following this incident, I came up with the idea of a product that would empower developers to build and update their APIs confidently.
Keep reading
APIs have become increasingly popular over the past few years, enabling products, projects and people to connect. In this article, we will try to present a snapshot of the most popular solutions available as of August 2022. We did our best to avoid bias, but some technologies are not mentioned on purpose, as we want to focus on the most used/popular.
Keep reading
OpenAPI is a standard for describing APIs (Application Programming Interfaces). The OpenAPI specification (or OAS) defines an open and independent description format for API services and allows both humans and computers to discover and understand how an API works and how to interact with it, without the need to look at the source code. More specifically, OpenAPI allows to describe, develop, test, and document APIs conforming to the REST architecture, to create RESTful APIs.
Keep reading
This week, Twilio published OpenAPI definitions for all of their APIs. Let's see together the small steps we can take to transform those definitions into a nice looking API Reference documentation page which tracks API changes automatically.
Keep reading
Do you have more than one API that you share with your customers or your team? Or, multiple versions of one API? If you do have many different API specifications, it can be difficult to organize and share your documentation in a coherent way. This is why Bump developed hubs.
Keep reading
At Bump, we are committed to ensuring that your API documentation is beautiful and always up to date. To demonstrate the power of our tooling, we're going to walk through the creation of an API (and, more importantly, its documentation). As we create the API and modify it, the power of integrating with Bump will become more and more apparent. And this is why we are here: to make everyone's life easier: easier for the development team, the documentation team and - of course - easier for your customers to understand and stay abreast of any changes to your API.
Keep reading
This week, version 3.1 of OpenAPI has officially landed after several beta and release candidates. This is a great news for the REST API community, as some important changes are coming with this version. Congrats to all the team behind this huge step forward!
Keep reading
As you may know, Bump was one of the first SaaS products in the world to support AsyncAPI 2.0. When the new version of the specification was released in September 2019, we decided to start working on it, and we released a first beta version 3 weeks later.
Keep reading
