1. 12

Anecdotally, I see a high level of dissatisfaction among developers who consume third-party APIs. Are these anecdotes merely a rant, or are third-party APIs inherently difficult to use?

What are some examples of APIs you’ve used in the past that you feel are well engineered, well documented and easy to use?

  1. 8

    I was impressed with Stripe’s API from day one (years ago). It was a breeze to implement things with, is well documented, has a library/package for every major language, and has a well-thought-out system of deprecation and backward compatibility that, honestly, let me upgrade API versions on my own schedule, which was sometimes more than a year after a new version came out. An order of magnitude easier than, say, adding Paypal to your site.

    1. 6

      Stripe is very good for what it does, but I don’t exactly enjoy it either. There are many layers of indirection, and they keep adding more as they expand the functionality. For example, you can’t say “here’s a token for a card and an e-mail, make a new paying customer”. You make a customer, you then add a payment source, then hook up product-payment-customer to create a subscription object. It makes a lot of sense from data modelling perspective, but has me really scared about error handling between the steps.

      1. 1

        I worked on integrating Stripe this week, and I came to the same conclusion, which came as a bit of a surprise since I’ve seen a bunch of people rave about it.

        I also dislike the Go client library. It’s rather weird. I actually ended up rewriting a much simpler Go Stripe library.

        1. 1

          Can you and the parent just do this transactionally? If one step fails, roll it all back. Of course there are still issues, and I haven’t used the Stripe API but that’s why I’m curious.

          1. 3

            The Stripe API doesn’t have a concept of a transaction, so a rollback would be more API calls, and then you have a Byzantine generals problem.

            The approach I take is to make it idempotent: “is there a customer already? No, then create one.”, but that’s more code, and needs handling of race conditions as well.

            1. 1

              Interesting, thanks for your insight.

        2. 1

          One thing that we’ve seen a lot of is being able to save a card to a customer, for it to be rejected immediately afterwards for a charge.

          I think this is Stripe’s way of exporting the different possible failure models…. but it is a bit frustrating that you can’t ask Stripe to just atomically do the thing for you.

          The Python library is very nice and makes a lot of stuff easier though.

      2. 4

        Let’s Encrypt has been a really enjoyable integration experience, and the ACME spec it’s based on is pretty easy to follow.

        1. 3

          I don’t use any APIs for “real”, paid work, only for side projects. The one’s I’ve used and have been satisfied with are

          • Bitcoinaverage - clear docs, I was able to implement the required authentication with no problems. Pricing structure is way more than I’m prepared to pay for my use case, but the free tier suffices for my needs.
          • HackerNews - easy to use, clear docs, fast
          • Reddit - a bit more of a pain to get going, but once it’s done it’s pretty damn solid and fast.
          1. 3

            Blizzard’s Battle.net API is surprisingly good. I’ve written a clojure library to pull some stats (I did play WoW and Diablo 3 from time to time since then) and I didn’t have to change too much over the years (61 commits in 8 years) and it never really got in my way. Keeping it stable would’ve been good enough on its own, really.

            But I’m not sure they’re going off in the wrong direction again, afaik the 2010-11 version was rewrittenfrom scratch, then they didn’t touch it for a few years, then they outsourced it to some company and now they have https://develop.battle.net/ which seems to be inhouse again. I think moving to OAuth was the only real breaking change, but gladly auth is easier to encapsulate and change than if they had shuffled all the endpoints.

            1. 3

              I’ve blogged about bad APIs before and in there I pointed out that Amazon S3’s API is pretty well-designed, especially considering how huge it is. The Dutch payment provider Mollie’s API is one of the few that are actually good in all respects.

              1. 3

                GitHub API v3 is nice to use. Just dumps JSON for objects living at predictable URLs. Documentation is sometimes sparse, but the data isn’t very complicated.

                1. 1

                  I’ve only used it through their python library and it’s nice and easy to use, especially compared to GitLab’s. GitHub is simple and straightforward to get data I need as well as understand what’s a separate call. I was surprised quite a few times in GitLab for what’s a separate api call can included with a call to project or whatnot.

                  Although I limit my use to read-only scraping of metadata to eliminate project and compliance reporting.

                2. 2

                  I’m using https://tapis-project.org/ at work and I think it was well designed.

                  1. 2

                    DarkSky API is nice. I used it for personal projects when I needed weather forecast data.