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.
We’ve migrated almost completely to a Gitbook docs site hosted on github pages.
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.
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
cURL examples ready to use with
Python coming soon!
Postman for the whole API
We realize that not everyone uses
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.
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:
- 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!