Introducing the API Explorer

We are happy to announce the launch of our API Explorer, our clients’ most requested feature.

Sending a first request is the last mile of an API discovery. As setting up an API client or using cURL in a CLI can be an endeavour for API users, we made things easier, by integrating the API Explorer into your documentation portal.

With the API Explorer, enable your users to go from API discovery to API usage, in a single place.

Send requests, right next to the API documentation #

It can be difficult for API consumers to understand the complete behavior of an API, that’s one of the reasons we make documentation. To ease the API’s discoverability in the Explorer, the request form is automatically generated with the right field types, based on the OpenAPI definition. No more Lorem Ipsum inside a date picker.

Readability is key in a context of discovery. A dedicated view for the API Explorer next to the documentation means focusing on what’s important: the customer’s request, and the API’s response, while keeping the documentation just one click away.

Deep support of OpenAPI #

Your API definition file is a contract between you and your users. That’s why we went all-in on supporting the OpenAPI specification in our API Explorer. From simple properties such as strings and booleans, to more complex ones such as arrays of objects or oneOf/anyOf, try any sort of request, based on any API design.

Request sharing #

Pre-defining and sharing a request can be really valuable for API maintainers, to:

• onboard new clients with a ready-to-play getting started,
• facilitate customer support,
• detect inconsistencies between the API definition and the live API,
• help debugging, …

API Explorer users have a one-click sharing option, providing a unique link that will autofill the request form with the shared values. Let people reproduce the exact behavior you wanted to show them.

Only the request is shared (the authentication method and the response are not).

When your API evolves, Bump.sh automatically detects if a shared request has become obsolete, alerts your users of possible field changes, and provides them with a diff summary comparing the two versions.

Secure by design #

Testing requests sometimes involves using sensitive or confidential information. That’s why we built it safe from the ground up: we will never see any information about your APIs. Requests, execution and sharing are handled 100% client side.

For APIs that don’t allow CORS requests, we built a proxy that makes it work without any specific configuration on your side. This proxy called cors-toujours is 100% open source, and hosted on a different server with no logs or data access.

Everything remains between the API consumer and the API itself.

Help your users discover your APIs with mock servers #

Our freshly announced partnership with Microcks gives a hint about our next focus: we are looking into ways of enhancing the discovery experience by streamlining mocking capabilities.

A mocking server creates a playground to deeply play with the API, without the hassle of setting up a demo server or impacting the production server.

Interested in setting up mock servers for your APIs? Contact us!

What it means for us #

We are really proud of the first version of the API Explorer. It’s a new pillar in our vision: to create a next generation documentation platform that brings multiple tools together with one goal: to provide the smoothest API adoption possible for API consumers.

The API Explorer is currently in beta. You can request access here.

And last, but not least, you can discover it now with our demo API!

Live demo #

Yoan Gross, our Product Manager/Designer, made a demo to explain our vision and approach.

Get feedback from users

Because feedback from real-life users is the best way to improve your documentation, our last update introduces a new “Give feedback” button.

The x-feedbackLink object can be added directly in the info object of your API definition file.

By letting you redirect this button to any link, we want to give you the freedom to choose the type of feedback you want:

• A pre-filled issue in your GitHub repository using a template,
• A nicely designed form,
• An email to the support team, …

Check our dedicated help page →

As always, don’t hesitate to let us know what you think of this feature! You can even use our “feedback” button on our dashboard!

Access management

It’s been a while since we added the first pillar of our access management system. It gave documentation maintainers a way to grant access to internal users (“members”) and external users (“guests”).

As our customers’ documentation reader bases grew, the way we handled user administration needed to evolve.

Say hello to the improved access management page, designed to easily manage members and guests from a single place. The new table shows more users per page and offer sorting options. You can also see which resources guests have access to directly from this table and revoke their accesses when needed.

On another note, we know that SSO can be very handy for companies with a lot of users. By working closely with our clients, we improved our SSO support to allow two SSO connections for the same organization:

• One for for internal users (“members”),
• One for external users (“guests”).

The SSO login page can now be customized with your company’s logo, providing a seamless experience for your users. Learn more about SSO here →

We hope these improvements will make it easier for you to manage access to the platform.

As always, we warmly welcome your feedback!

Love Cycle - July 24

We have been busy improving Bump.sh through small enhancements, specific user requests, while globally polishing the product. We call these moments “Love Cycles”.

Here is the list of every small change we made.

As always, we love to hear about any features you would like to see added to the product. Send us a message at hello (at) bump.sh!

Improvements:

• When you are subscribed to an API changelog, the link inside the email notifying about a new change now redirects to the specific change page.
• Single change: we worked on the page to remove duplicated information, and put the focus the deployment date and change id, that can both be useful depending on who reads it. We also put some love on the mobile version.

Quality of life:

• API keys, that let you configure automatic deployments or use the CLI can be set at the organization level, at a Hub level, or at a doc level. By default, you can always use an API key from a parent resource (for instance, the API key of the Hub or the Org that the doc belongs to). We made it clearer in the UI by displaying the parent resource API key in the Automatic Deployment settings page. It still is possible to create a dedicated key for each resource.
• Deployments page: we removed the tabs allowing to filter between All, Released and Not Released deployments to improve the page’s readability. It is still possible to filter deployments by State (Enqueued, Deployiong, Deployed, Errored).

Fixes:

• Webhooks in documentation now display the generic URL https://webhook.example.com.
• We fixed a visual bug on selects, that could make the user think that multiple items were active.
• We fixed a bug that made the title and description of an more recent change disappear when an user unreleased an older deployment.
• Timestamps are now displayed using the browser’s timezone.

Changelog entry page

We have recently improved the changelog to make it easier to share updates to your API documentation.

In addition to the continuous deployment flow of the changelog, you can now click on each entry to view an individual page for a specific change. This option allows you to easily share a link directly pointing to the changes you don’t want your API consumers to miss, whether they are members of your organization or partners.

Our API documentation allows you to easily test the rendering of these new pages, as shown with this example.

We have many more updates coming to the changelog this year, and we can’t wait to show them to you.

APIs.json support

Looking for a comprehensive file listing all the APIs inside your hub? We’ve got you covered!

We support APIs.json, to automatically generate a JSON file out of your hub content.

To access the JSON, simply add /apis.json at the end of your hub URL. It contains the description, type, version, documentation URL, and more about each API.

For example, it can be used to:

• Check in an automatic CI context that a precise list of APIs is published on your hub
• Add your APIs to an API search engine (e.g. APIs.io)

We have also published a detailed guide to help you get started with APIs.json.

You can try it out on our demo hub here →

Love Cycle - April 24

We have a tradition of scheduling what we call Love Cycles between our development cycles: times dedicated to improving Bump.sh, responding to specific user requests that we find relevant, and providing a general polish.

Our last Love Cycle has recently ended, and we wanted to share with you all the small changes we’ve made. If you have a feature in mind or a need, don’t hesitate to share your feedback with us at hello (at) bump.sh!

Improvements:

• Overlay Support: Overlay is a new feature (beta) of OpenAPI that allows applying a layer over an API document without modifying it, to adapt to a specific context. Now supported by Bump.sh, we also added to our CLI a new command. Feel free to read our recent guide on the topic!
• Examples will now display correctly regardless of the chosen format. Bonus for those in XML which will also display the appropriate highlight.
• [OpenAPI] Improved support for externalValue which now displays a link to the designated resource.
• When using the GitHub Action for a diff, we now add a link to the preview of the result directly in the PR.

Quality of Life:

• We have improved the appearance of highlights during navigation on documentation, to make them more visible and comfortable.
• Navigation has been improved for logged-in users, by adding buttons for quick return to the Dashboard.
• From now on, the timestamp of your deploys and other actions will be based on your browser’s timezone instead of GMT+1 by default.
• We have added and modified some warning messages to make them more explicit.

Fixes:

• We resolved the issue with discriminator values not always mapping correctly in certain specific cases. Special thanks to Phil Sturgeon for pointing it out and having a thorough discussion about discriminators with the team.
• The generation of some API keys was not always going smoothly, but this is now fixed.
• [AsyncAPI] The binding support is now properly applied at the channel level.

New dashboard experience

It’s been a big project that we’ve poured a lot of energy and even more love into, and our new dashboard is finally available to everyone. It’s become a true home for your API ecosystem and everything that happens within it. From creating a hub to exploring your documentation, everything has been redesigned to offer you the best possible experience.

We’ve also put the finishing touches on another major change: the removal of individual spaces. To discuss this, let’s take a step back.

In its early days, Bump.sh was designed for individual developers but quickly became collaborative. The vast majority of our users now work in teams. Until now, each user had their own personal space and could create and/or join organizations. In practice, many personal workspaces remained empty and unused, there was often confusion between the two, and the experience wasn’t the most comfortable.

To put it briefly, all documentation and hubs now belong to an organization. For our users, nothing changes or hardly anything: your existing hubs and documentation have been migrated to an organization bearing your username, and your URLs still work. We have naturally adjusted our Free plan to not impact our users under this plan: it now includes an organization (yours) with all its APIs publicly accessible as before.

For more information, feel free to check out our dedicated help page.

API keys

The API key, also known as a token, grants access to our API and allows you to integrate it into your continuous integration workflows. So far, it was working at the scale of a specific hub or a documentation.

We are evolving API keys so that they can now operate at the organization global level and everything it contains. This change aims not only to greatly simplify the use of our API but also lays the groundwork for upcoming features, such as user management or the creation of documentation/hubs/etc…

For this migration of API keys, we made sure not to touch the existing ones to allow your existing workflows to continue functioning without any issues.

Help Center Remastered

Writing beautiful documentation is something that we deeply care about at Bump.sh. Therefore, we have spent the last few months completely rewriting our product documentation, including a structure overhaul, to address as many questions as possible and to assist you in better understanding and leveraging Bump.sh.

In it, we cover the core concepts of API documentation, solutions to help you integrate Bump.sh into your tools and workflows, and all the features, from customizing your documentation to deployment options.

Our help center is open source: we warmly welcome any suggestions or corrections. You can consult our contribution guidelines to learn more about this.