Adeel Ali January 30, 2018

Developer Experience Beyond API Docs

If you talk to a man in a language he understands, that goes to his head. If you talk to him in his language, that goes to his heart — Nelson Mandela

May I ask you to name a few APIs with a phenomenal developer experience? I have asked this question many times, and the answer was hardly any different. There is a reason why Twilio, Algolia, Stripe, etc. are loved and accessed by millions of developers. While the majority of API portals are limited to HTTP Docs and API reference, you’ll find the best ones taking the developer experience way beyond that. They do so by:

  1. Freeing up their developers from redundant tasks, i.e., provide SDKs/Helper libraries, tutorials, code     samples, test cases and other features to make API consumption very simple.
  2. Speaking the language of their developers, i.e., they keep everything from simple How-Tos to intricate SDKs in languages their developers love to code in.
The Common Developer Experience Ingredients Found Among APIs
The Common Developer Experience Ingredients Found Among APIs

However, providing a great experience and serving a variety of developer communities is easier said than done. API owners typically need a team of language experts, technical writers, and software testers to begin with. Still, the time to market after every API update and keeping things in sync take ages. A reason that great API portals are still rare to find. We, at APIMatic, believe that this problem can be solved by maintaining a machine-readable description of an API and let automation taking care of the rest.

One of the biggest killers of productivity is redundancy. By performing the same task multiple times, you are not only wasting time, but you are also undermining creativity and ingenuity - Kathrine Farris

Enhancing Developer Experience via Automation

Automation works on a simple principle — keep humans focused on what’s creative, and delegate to machines what’s redundant.

APIMatic mission is no different — using automation to delegate the redundant work to machines, we want developers to solely focus on what’s unique and creative. APIMatic’s Code Generation As A Service has been a great success for continuously integrating internal APIs. Today we’re taking our mission to the next level by introducing API portals that are automatically generated using an API description. Not only the HTTP docs but also with features-packed SDKs, language-specific docs & tutorials, reactive code snippets, test cases, and API transformations. These components — by taking care of repetitive problems — can become a dev’s best friend, as you'll find in a compilation of 15 great APIs.

These and other APIs will help you supercharge your abilities. With repetitive problems taken care of, you’ll be free to focus on the part of your job that only you can perform — Adam DuVander

What’s Different From Other Docs Solutions?

There exist over 30 solutions to document your APIs, so why create a new one? The answer lies in the fact that the existing portal solutions are great in providing generic content with attractive themes, but the generated portals are not as comprehensive as listed in the table above. More importantly, the developer-engagement content (such as SDKs, Code Samples) is either missing or requires manual efforts (imagine documenting the authentication flows for the developers of +10 languages). Thanks to the code-generation engine of APIMatic, we are able to offer a distinct and customizable solution that covers both generic and developer-specific content. The notable components of the portal are the following:

Developer Experience Beyond API Docs

  1. SDKs for a variety of platforms: Developers love SDKs / Client Libraries — simply because SDKs lift heavy burden of communication with an API, and let developers focus on app design and business logic.
  2. API Console: Try out the API right from the docs using your input.
  3. Reactive Code Samples: The quickest way to the first hello world. Get a complete running sample code in your language containing no dummy or static content. Learn More.
  4. HTTP & Language Specific Docs: API reference in HTTP and web/mobile languages to take your API to all major developer communities.

Developer Experience Beyond API Docs

5. Custom Sections/Guides: Help your audience by adding custom sections or guides to your portal.

6. API Export in over 15 formats: Transform your API description in a format of your choice. Benefit from a wide range of tools available associated with any format, not just one.

7. Deploy on Github, or Publish Packages: Don't want to download SDKs and compile by yourself? You may deploy the code at Github, or publish compiled packages at respective language repositories.

8. Tailored Tutorials: No more manual technical writing and static/outdated screenshots for your API docs.

9. Usage Instructions in major IDEs: Make your developers feel at home by providing everything in their favorite development environment. All major IDEs are supported.

Host New, or Embed in Your Existing Portal

From the portal design to hosting and white-labeling, we cover everything. However, you might have invested a lot of effort in your current API portal, and love its design and content. The good news is that you can retain all of your hard work, and still enhance the developer experience of your portal via embeddable DX components. Learn More

The DX components being embedded into an existing portal
The DX components being embedded into an existing portal

The best of 2 & 3 Column Designs

The trendy 3-column portal designs are great to depict code separately to the text, while the classic 2-column ones are good to document guides and general content. We're bringing the best of both in a single portal. Have a look by yourself.

An API to Continuously Update Your Portals

API changes are inevitable, but reflecting those changes to your published portal is typically a nightmare. A reason we’ve built an API to help you integrate the portal generation within your CI/CD pipeline. Now make API changes as often as you like, and get a refreshed portal ready, instantly. Learn More.

Customize The Way You Want

Initially, a portal is generated with default settings, but there are two types of options to let you customize almost everything the way you want. The first type is about changing the design and appearance of the portal, while the second type deals with changing the code-generation settings using an advanced API editor.

That's It

Please give the Developer Experience Portal a try, and let’s know about your experience. We’re all ears for your valuable feedback and suggestions.