Love cycle - April 25

Every now and then between larger product cycles, the whole team gets together to polish the product by working on small enhancements and user requests, in a time called “Love cycle”.

Here’s a list of what’s been worked on.

Improvements:

• You can now easily list all your organization’s hubs using the new GET /hubs endpoint in our API,
• Our GitHub Action has been updated and now supports overlays,
• Bump.sh CLI:
  • A message is now displayed at every document update, so you know the CLI is running and updating the preview properly,
  • When using bump overlay, we now display a message if an overlay doesn’t match anything,
  • When using bump deploy, an explicit message is displayed if the target directory doesn’t exist.
• Security badges are now displayed for webhooks,
• CLI and GitHub Action code samples in your hub/documentation settings now contain real slugs and tokens to speed up Bump.sh integration into your workflow.

Fixes:

• Autogenerated date-time and time string examples now follow the ISO RFC 3339 format recommended by OpenAPI, and are displayed as 2017-07-21T17:32:28Z,
• The markdown support in documentation has been audited and multiple visual enhancements and fixes have been applied, improving visual hierarchy and readability,
• Security Schemes from OpenAPI V2 definition files are now displayed in the documentation,
• The top navigation has been reworked to offer a consistent experience across all views (Documentation, Changelog, API Explorer),
• Security badges have been reworked to ensure that they always correctly redirect to the authentication page and are displayed consistently,
• Descriptions of array[object] are now displayed in the documentation.

As usual, don’t hesitate to reach out if you have any questions, feedback, or features you would like to see added to the product. Knock at hello@bump.sh

Introducing state badges for operations and properties

Operations and properties go through multiple states during their lifetime, from unstable to beta or release candidate. This information can be crucial for your users. And more importantly, it can be completely specific to your API lifecycle. That’s why we are introducing a new property named x-state.

This custom property is a string that can be added inside an operation or a schema to identify it with a custom badge:

    paths:
    /diffs:
        post:
        description: Create a diff between any two given API definitions
        x-state: Technical preview # x-state flag at the operation level
        requestBody:
            description: The diff creation request object
            content:
            application/json:
                schema:
                type: object
                properties:
                    url:
                    type: string
                    format: uri
                    x-state: Still unstable # x-state flag at the schema level
                    description: |
                        **Required** if `definition` is not present.
                        Current definition URL. It should be accessible through HTTP by Bump.sh servers.

In this example, we added an x-state property to the operation itself, and one of its properties.

Learn more about it in our help center

As always, don’t hesitate to reach out if you have any feedback regarding this new feature.

API Explorer - Authentication support

Authentication is now supported for APIs providing authentication methods.

We currently support:

• HTTP: Bearer/Basic,
• API keys: Header/Query string/Cookie,
• OAuth2: basic support through a header token field.

Users only have to define it once to use it on any of your API operations that require it.

Want to try the API Explorer? You can request access here.

The API Explorer is still in beta. We warmly welcome your feedback.

Mermaid support

Sometimes, the best way to explain something about your API is to do it visually. That’s why we’re announcing Mermaid support!

Diagrams and charts are powerful tools, that can be used to share updates on your API development roadmap or give key information on data processing flow, for example.

Discover the full list of diagrams and charts supported by Mermaid here.

To generate one, add a code block declared as mermaid inside a description or content property:

  get:
    description: |
      ```mermaid
      erDiagram
        CUSTOMER }|..|{ DELIVERY-ADDRESS : has
        CUSTOMER ||--o{ ORDER : places
        CUSTOMER ||--o{ INVOICE : "liable for"
        DELIVERY-ADDRESS ||--o{ ORDER : receives
        INVOICE ||--|{ ORDER : covers
        ORDER ||--|{ ORDER-ITEM : includes
        PRODUCT-CATEGORY ||--|{ PRODUCT : contains
        PRODUCT ||--o{ ORDER-ITEM : "ordered in"
      ```

This example would render the following diagram (see it live):

The support of Mermaid is part of our global Markdown support. Learn more about it in our help center.

As always, don’t hesitate to reach out if you have feedback about this feature!

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 →