API Reference Updates (Q2 2021)

🎉 Meet the New API Reference

We know how critical your API Reference is to making your docs successful, so we've been working hard on a major update to ReadMe's API Reference format that makes using your APIs even simpler (and more fun!).

In this redesign, we’re bringing ReadMe’s code builder and dynamic call request history front and center, so developers can generate code and see exactly what’s happening with their calls in real time. Along with this, we’re upgrading your site header to be consistent across every page, so switching between the Reference and other sections of the docs is seamless.

For our current customers who are familiar with the current version, we’re also addressing the most common feedback we hear around clunky nested forms, Try It Now, response object schemas, and navigation between endpoints. Overall, the new Reference makes it easier for developers to get started with new APIs or debug issues with APIs they’re already using.

🗓 Product Rollout for Current Customers

Currently, the new Reference is available to new customers as of May 18th and in limited beta for current customers to preview published docs using the new design. We will use this beta phase to get product feedback and discover edge cases or bugs across the wide variety of ways our customers use ReadMe as we work toward a migration for all current customers.

📘

How to access your preview 👀

If you are current customer participating in the beta program for the new Reference, you will receive a unique link to preview your docs using the new design from your CSM or from the ReadMe Product team. Using this link will not impact your published docs in any way! If you're interesting in joining the beta, please reach out to us at [email protected].

We are not yet migrating current customers to the new design and expect to kick off that process in June before deprecating our legacy Reference at the end of 2021. Customers will be able to control when you switch over, so you can make any required design or content adjustments on your own schedule. More to come on this process soon!

🥳 What’s New & Key Product Improvements

We added new functionality and made a slew of improvements to help new developers get started with your APIs faster, debug integrations they've already built, and improve support for OAS. When you're exploring your beta preview (or even going through our docs right now, as they're using the new design!), here are a few product highlights we'd love to call out!

One Endpoint per Page and Unified Header

Perhaps the biggest change you’ll notice, or at least the one you’ll notice first, is that we’re making each endpoint its own unique page rather than allowing for continuous scroll. This all-in-one page approach allows each endpoint to be its own entry point to using the API, rather than forcing developers to jump around the docs to find API keys, how to install SDKs, find Auth instructions, etc. With this approach, developers have everything they need on every page, and each endpoint loads faster.

In addition to looking 🔥, we've unified the header navigation across the entire site, so it's consistent as you switch between Guides, API Reference, and other pages of your docs. We've also improved mobile navigation to keep the header menu easily visible.

Dynamically Generate Code in Real Time

We’re making the ReadMe code builder more prominent and useful. Tons of docs have code samples, but we’re taking it further by allowing devs to dynamically update these samples using the form inputs. They can generate a copy-and-pastable code snippet to use in their integrations as they’re exploring the docs and learning about the API.

We've also added simple mode, powered by ReadMe's api npm package. This basically functions as an SDK builder for your OAS file to abstract out complexity and streamline calls. It’s on by default (and not branded as ReadMe in any way!), so your docs are magically simpler without any extra effort.

Interactive API Logs Experience

See your request history and status of your calls at the top of the endpoint page, and easily filter the date range. Each request has a unique link you can use when troubleshooting support requests, so you and your developers are seeing the same context.

Out of the box, calls made with the Try It playground show in the request history for real time exploration of your APIs. With a little extra authentication setup, you can log users into your docs to pass their API key or other data automatically.

And if you're using API Metrics, developers can access their recent API logs right in your Reference with a trendline that makes it easy to eyeball spikes in call volume for further investigation.

Improved Support for the OpenAPI/Swagger Specification

  • Nested Response Object Schema: Quickly click on a status code to see the response schema object for real-time troubleshooting.
  • Easily selectable request examples: Now you can build an example object within your spec file, then choose it and run it, seamlessly!
  • Multiple server URLs and server variables support: Easily choose from multiple listed servers or use data variables in your URLs, like a unique id.
  • More default code sample languages: Quickly switch between your most popular languages or use the dropdown for extended language support. Your chosen language will be saved as you navigate between endpoints as well!
  • Clearly marked required parameters and improved nesting: Tell at a glance which parameters are required as you build your code sample in the form. Improved nesting ensures your form stays clear and usable (even several layers "deep"!).

👩‍🏫 Customer FAQ

How Can I Test the New Reference?

You can preview the new Reference by adding your ReadMe subdomain into this url: <yoursubdomain>.readmepreview.com. If you don’t know your subdomain offhand, you can find it in your project settings under Configuration > Custom Domain > ReadMe subdomain.

Right now, we’re still in the early stages of the beta and it’s not yet possible to switch permanently to the new design. We’d love to get your feedback on the preview, and we’re expecting customers to be able to start migrating in late May or early June.

Do I Control When I Switch and How Quickly Do I Need To Switch?

Yes, you’ll be in control of when you migrate! This will be configured by you in your project settings or manually in coordination with us. We’ll be supporting the legacy Reference through the end of 2021 to allow customers plenty of time to make any adjustments you need in your content or CSS.

What Happens to My CSS, or How Can I Update My CSS for the New Design?

Since we’re using new class names in the new Reference template, we’d expect customers with a lot of custom CSS to need to make some updates. However, we also addressed some common cases customers are using CSS for today to reduce the need for it. We took inspiration from the best practices from our customers’ docs in order to build something that works great right out of the box.

📘

Using CSS variables

We've made some updates to ReadMe's CSS to make customizing and updating the design of your hub simpler with CSS variables. Learn more here.

That said, once you have access to the preview, you can work on new custom CSS. The class names are unique to the new Reference, so you can do this in advance without impacting your current Reference. Any changes you make in production will be reflected in the preview, so you can test out CSS in advance of switching permanently.

Do I Have To Switch From Continuous Scroll to One-Endpoint-per-Page?

We know it’s an adjustment, but we can share some more context on why we’ve made the new Reference only available with one endpoint per page. We want to ensure every entry point into your docs provides all the information that a developer needs to get started, including authentication. This way developers aren’t needing to jump around in your docs to find header authentication, packages they need to install, API keys, error examples, etc. Everything they need to make a call is right there.

Having each endpoint as a unique page makes that possible — it would really slow down performance to need to load all of that content over and over again as you scroll. Continuous scroll behavior is just accepted as standard (going all the way back to Stripe or Twilio’s original 3 column docs), even if it’s not the best design solution. While we know it’s a change, we’ve actually gotten really positive feedback on this change from other customers after trying it out.

How Can I Consolidate Content Pages and Set Up Redirects?

If you were previously using continuous scroll, you may end up wanting to consolidate some of these content pages into a single page. If that's the case, you can make those content changes directly in your ReadMe admin dashboard and publish them whenever you are ready. If you deprecate any pages as part of this process, be sure to set up redirect links following these instructions.

✍️ Using the Manual Editor for Your API

The simplest way to get started with ReadMe is to use an OAS file, but if you don't have one, you can also use our manual editor to document your API. There are a few tradeoffs to keep in mind if you go this route! Some advanced functionality is not supported in the manual editor:

  • Complex OAS features such as allOf, anyOf, and discriminators
  • Choosing from multiple server urls or using server variables
  • Rendering complex nested objects
  • Supporting multiple authentication methods
  • Selecting default autogenerated code sample languages

If you need this functionality for your API Reference, we highly recommend documenting your API using the OpenAPI Specification. We've had customers outsource this task on freelancer sites like Upwork with good success if you aren't able to do this in house!


Did this page help you?