Skip to main content

DevStack

Introducing dev.bandwidth.com

Bandwidth
Bandwidth
Published:

December 15, 2016

Updated:

March 29, 2023

Share
Laptop with Bandwidth devdocs on screen

Over the past few months, we have been working to redesign our documentation page for our Communications API Platform and Dashboard products.

Why the update?

As Bandwidth has grown as an API company, we wanted to refresh our documentation with a focus on the developers using the API.

So, we went out and gathered feedback from all our local developers and read blogs. Lots and lots of blogs. The biggest take-away was ‘show me code!’. So we went out and searched different doc sites that put code first and rich with examples.

Our basic requirements were:

  • Live code samples with our own SDKs (not only generated)
  • Our domain name
  • Global Language preview options
  • Markdown -> html conversion
  • optional (Swagger/RAML -> HTML/Markdown)

We set off with our requirements and found 5 reasonable options:

Of those we built and tried Stoplight, Slate, and Gitbook. But we seriously considered all the options.

What’s new?

We’ve migrated almost completely to a Gitbook docs site hosted on github pages.

Gitbook

Entirely open source docs and code samples

The entire doc site is generated from Markdown files hosted on github. That means any one that uses Bandwidth can contribute to the docs pages. Find a bug in the Communcations API Platform documentation? Fork the repo, make the fix and open a pull request. We’ll review the change and deploy as soon as possible. Want to add an example to the How-To guides, same procedure, fork the docs site, add your sample, and open a pull request.

Code EVERYWHERE

The new docs put a focus on the code giving you a heads up view on what you want to do. Once you select your language, the site shows you the relevant code sample for that language where available.

We currently have Javascript, Ruby, C#, and cURL examples ready to use with Python coming soon!

Code Shot

Postman for the whole API

We realize that not everyone uses Python, Javascript, Ruby, Bash, or C# to test out their code. So we put the whole API in a Postman Collection. Click the Run in Postman button on the Rest API page to get the collection to run locally.

Postman

Coming Soon

We’re not done with the docs site just yet. We’re still working to make developing with Bandwidth an awesome experience.

  • Code Samples for ALL supported SDKs: Java, Python, PHP are missing
  • Dashboard(Iris) documentation migration to new layout
  • Swagger(OAS) & RAML site generation
  • Swagger(OAS) & RAML export. Download the API definition
  • More How-To guides. New and more how-to guides focusing on real world use cases
  • Migration Guides to ease the transition to Bandwidth from other Communications APIs

Thanks for reading! We can’t wait to hear your feedback!