16
32 Comments

What do you hate most in API onboarding experience?

Hello Indie Hackers!

We are doing some research at Blobr on the API onboarding topic, we are very interested to know what you experienced with integrating APIs.

What do you hate most in API onboarding experience?

You can answer in the comments or complete this quick survey — it takes 2 minutes. :)

  1. 3

    Here are the things I hate the most while working with a new API:

    1. Most APIs require digging 2-3 pages before you get to know what are the endpoints, request parameters and return data. For me, Unsplash API nails this problem right on the landing page itself with the gif in the hero section and the interactive widget in the next section.

    2. Poor SEO of documentation pages e.g. when I search "How to save emails in Mailchimp list with api" I should get exactly that. That's the ideal expectation but that's not how things are.

    3. Lack of a dedicated "Quick Start" section that lists out all the endpoints along with examples of how to use them

    4. Poor documentation. Period. Some of my frustrations are:

    • Mismatch between schemas and actual data (as someone mentioned)
    • The example states that you have to pass X and Y in order to make a call but doesn't tell you where you can find X and Y in your account
    • Lack of an inline sandbox to try out the api (with your own data) from within the documentation. I know this is too much to ask for but will greatly improve the experience
    1. 1

      Cool Feedback. Inline Sandbox looks like a great way to improve the experience. Do you have in mind a great API doc?

      1. 1

        Well, I haven't found a single doc that is perfect.

        However, I feel most UI component/design system docs are more engaging than API docs. For example, Chakra UI doc is amazing. It provides:

        1. a fast copy-paste mechanism
        2. a sandbox that lets you try what they are talking about in certain part of the doc
        3. an organised multi-column layout (doc topics on left bar, page topics on right bar and info in the middle). I feel this layout works the best but then again, it's my own preference.

        Now speaking specifically about API docs, I like what the Indian government tried to do with the Cowin API. To briefly explain, Cowin is a website that lets you book vaccine slots and these APIs enable you to check slot availability, generate vaccination certificate etc. What I like about this doc is:

        1. The "Try it out" feature that lets you test the apis with your own request parameters.
        2. They present all the information related to an api in one place e.g. request params, response data, response codes, schemas etc.

        But this doc still failed according to me because of abysmal UI design

        In addition to that, I like the documentation best practices put forward by Divio. Their approach towards structuring a doc works for me.

  2. 3

    At the beginning - lack of "Quick start" section with sample API requests.
    Later - lack of description of some parameters in endpoints

    1. 1

      Does the "Quick start" include the authentication too in your mind?

      1. 1

        Yes, everything to start from scratch quickly

        1. 1

          Ok, well, thank you for your feedback, we'll try to solve this :D. Don't hesitate to add your feedback by taking the 2 minutes survey it would be cool for everyone too!

  3. 2

    Lack of examples
    --------------

    If there are examples along with the documentation on when to use certain parameters along with the sample output, it would be great.

    Many times, just the description is given without telling the role of a particular parameter.

    If there is authentication required, please make a demo/sample request which doesn't require authentication just to check the output.

    Documentation is not a bonus. It is the actual work.

    1. 1

      It is always the thing frustrating the one building it and the one receiving it...

  4. 2

    How to use API endpoints together. A lot of documentations are just lists of endpoints + parameters without explaining the overall concept of how to use them. You need an introduction of some kind and tutorials on how to implement concrete use-cases (like Stripe does).

    1. 1

      Interesting! So based on your personal use case you have in mind when discovering an API, you would prefer that the documentation would be focused on the endpoints that are useful to you?

      1. 1

        Both. The API must be fully documented of course, not just how to use a single endpoint, but also how to use them in combination. Something I like about the Stripe documentation is that they have guides for common use-cases, like here: https://stripe.com/docs/billing. This helps to find a place to start and work from there.

        1. 1

          Ok I see, thank you for your feedback. Don't hesitate to give 2 minutes for the quick survey it would be interesting to see the overall results at the end (or to test our app if you want!)

  5. 2

    Authentication and poor documentation

    1. 1

      Poor documentation is terrible. What is the most frustrating for you?

      1. 1
        • Out of date info
        • Lack of examples. Worst of this type is typically java API docs. You get 100 pages of methods you'll never use, stating params, return values etc. Just give us a single example to use it with.
    2. 1

      What would you love to find in your onboarding experience that could improve authentication & documentation?

      1. 1

        I think up-to-date example to do something basic with the API that you are providing would be good.

        I state authentication to be frustrating because this is usually the part people get stuck with the most, and waste a lot of time.

  6. 1

    I personally hate when API's don't give you a html only implementation ie via CDN network of compiled javascript. That way I can create a page that tests the api without a full npm build

    1. 1

      Do you have an example where you thought the API doc is great?

    2. 1

      Interesting, thank you for your feedback!

  7. 1

    This is an interesting topic- will you share your results?

    1. 1

      Yes, we definitely want to share the results, but we need a good sample of answers to have something legit! What're your thoughts on the topic, did you take the survey?

      1. 1

        I'm more on the business side of things and don't often sign up for APIs myself. We are an API-based company though, and onboarding design is definitely a challenge.

        1. 1

          Okay I see, interesting! Would you be available for a quick chat to talk about it?

              1. 1

                Will ping you on Linkedin.

  8. 6

    This comment was deleted 3 months ago.

    1. 1

      Does it happen often for you? Is it because some breaking changes happened?

      1. 1

        This comment was deleted 3 months ago.

        1. 1

          Indeed, thanks a lot for your feedback

    2. 1

      I feel your pain! How do you manage to find a solution to this problem?

      1. 1

        it could be solved if api docs schema are autogenerated based on types in code,

Trending on Indie Hackers
My bootstrapped SaaS hit $22k MRR, AMA! 42 comments We’ve grown an open-source project from $1k to $10k MRR in 9 months, AMA! 28 comments I’ve cleaned up my startups’ landing page, can you please trash it for me? 24 comments How to use React useReducer hook like a pro 10 comments Acquisition Channel Opportunities: Facebook, the App Store, Reddit Ads 9 comments Quran API - Free and simple access to the holy Quran 1 comment