8 February 2024: Deprecating the API method block in favor of OpenAPI improvements

We’re making big improvements to our OpenAPI support and API documentation rendering — so we’re replacing the editable API method block with a standard text alternative.

We’ve heard your feedback, and we’re working on some major improvements to how teams can document APIs in GitBook. It’ll give developers a great reading experience, and provide the right information at a glance. We can’t wait to share this with you in the coming weeks!

However, this also means we had to reconsider how people document API using GitBook today. As a result, we’ve decided to deprecate the API method block and make some big improvements to our OpenAPI block.

🖼️ Context and reasoning

Up until now, you could document APIs in GitBook in three different ways:

1. Generating API documentation using an OpenAPI definition

   This is by far the most advanced and flexible method. Teams can rely on their API definition and easily maintain up-to-date API documentation. We support the OpenAPI 3.0 standard to date. Here are a couple of examples:

   • Our own developer docs

   • Bird’s API documentation

2. Craft API documentation using traditional blocks This method gives you full freedom over what to display, and how. While this offers flexibility, you also have to update your documentation manually every time the API changes. Still, some people love documenting their APIs this way!

   • The Mews Connector API docs

3. Manually inserting API method blocks This method gave people control over what they displayed in their docs, but came with some drawbacks:

   • When the source API changed, someone had to update the block manually

   • The way the API method block rendered was inflexible, which didn’t meet our users’ needs

   • The block simply didn’t offer as much information and space as an OpenAPI block

From our perspective, the API method block was very restrictive in what it could support. It also technically limited our ability to improve the OpenAPI documentation experience to the quality we know you expect from GitBook.

📅 Timeline

• Monday 12 February 2024: You’ll no longer be able to insert API method blocks in the GitBook editor.

• Monday 4 March 2024: We’ll automatically transition all pre-existing API method blocks to regular text blocks — read on for more details.

🤖 What happens to your API method blocks?

On Monday 4 March 2024, we’ll automatically change your API method blocks into other, standard blocks. Here’s how an API block will look after the transformation:

An example of the depreciated API method block.

How the content will look after the transition, using standard blocks.

We’re confident that the editing and reading experience of translated blocks is going to be improved as a result. That said, we think API documentation is even better using OpenAPI definitions instead of manually written text.

👩‍💻 What’s changing with OpenAPI blocks?

OpenAPI is a standard that helps gather a lot of information about an API and present readers with that information consistently — and automatically. If you use definitions like Swagger, you can easily update the definition file when you update your API, and those changes will instantly sync to your docs, too.

The OpenAPI block improvements that we’re working on right now will show information like sample code to use an endpoint and a detailed list of attributes — all based on your API definition, rather than manual input. It’ll also make it easier to navigate between response types and languages for sample calls and show all the important information at a glance.

We’re testing the updated Open API block in our own developer documentation right now, so head over there to get a sneak peek. We plan to release it on the same day as we depreciate API method blocks, but we’ll share news on that soon.

If you have any questions or concerns in the meantime, please get in touch! We’d love to hear your feedback.