Latest updates and blog posts

Find here all the things to know about Bump.sh, API ecosystem and tech in general.
Tech

A Developer's Guide to API Design-First

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 Arrow right icon
Tech

CORS-ing the Boundaries: How We Built a Secure Open-Source Proxy Solution for Our API Explorer

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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon
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 Arrow right icon

We use essential cookies and optional ones for your experience and marketing. Read our Cookie Policy.