Microcks + Bump.sh: Testing, Mocking and Docs
This article explains how Bump.sh and Microcks can be used in tandem to establish a natural cycle of documentation, simulation (a.k.a mocking) and testing.
Keep reading
Latest updates and blog posts
Find here all the things to know about Bump.sh, API ecosystem and tech in general.
Tech
How Spec-First API Documentation Aids Partner Integration
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
Tech
Improve Your API with User Feedback
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
Tech
The Discriminator in OpenAPI Is Generally Redundant & Confusing
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
Tech
The "Don't Have Time to Create API Documentation" Paradox
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
Tech
Accelerating your OpenAPI Spec Generation with TypeSpec
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
Tech
The Hidden Value of Partner APIs
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
Tech
Writing an OpenAPI Document from the Ground Up
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
Tech
Introducing Arazzo: Describe API Workflows with this extension to OpenAPI
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
Tech
The Growing Need for Gateway Agnostic Developer Portals
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
Tech
How API Product Bundling Improves the Developer Experience
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
Tech
From SwaggerHub to Bump.sh, unlocking the power of Git
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
Tech
Incorporating API Documentation Guidelines Into Your API Style Guide
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
Tech
How Our API Docs Can Ease the Pain of API Deprecation
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
Tech
Git Workflows for API Technical Writers
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
Tech
Make your APIs Discoverable with APIs.json
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
Tech
Using README-style API Documentation to Enhance Your API Design
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
Tech
Improving Schema Component Documentation in OpenAPI Documents
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
Tech
Enriching Your OpenAPI Info Documentation for Understanding
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
Tech
5 Improvements to OpenAPI Operation Documentation
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
Tech
The Role of Technical Writer in API Documentation
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
Tech
API Documentation Checklist
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
Tech
How to use JSON Path
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
Tech
The Elements of Great API Documentation
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
Tech
Documenting PHP APIs with OpenAPI
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
Tech
Train Travel API: A Modern OpenAPI PetStore Replacement
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
Company
Revamping the Help Center
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
Tech
Documenting Ruby on Rails APIs with OpenAPI
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
Tech
Code-first: How to Generate OpenAPI from Code
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
Tech
OpenAPI & AsyncAPI $ref: Advanced Guide
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
Tech
AsyncAPI vs. OpenAPI: Which Specification Is Right for Your App?
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
Tech
Creating an API with Express.js using OpenAPI
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
Company
How Bump.sh works with… remote work?
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
Tech
Creating Better API Architecture Diagrams
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
Tech
A Developer's Guide to API-First Design
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
Tech
The Best API Documentation Tools for Dev Teams in 2023
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
Company
Bump.sh raises €4M to optimize collaboration in API ecosystems
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
Tech
What are the different API types?
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
What is OpenAPI?
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
Experiment
Playing with Twilio's OpenAPI specifications
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
Tutorial
Organize your API documentation with Bump hubs
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
Tutorial
Building your API: Design Mode
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
OpenAPI
Two OpenAPI 3.1 changes we love
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
AsyncAPI
It's time to make it official with AsyncAPI
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
