I'd love to get some more insights on your experience with this topic.
Do you integrate 3rd party APIs in your product?
Did you build your own private or public API?
What pains are you running into integrating or building these APIs?
I'm obviously not talking about your Googles / Twilios / Auth0s / etc. I'm talking about the longer tail of services that we don't want to build ourselves, but that there isn't instantly a big name service that provides it.
We would try one or two, and then find that they would work great in testing, but when you put any kind of load on them then they would regularly fall down. Similarly, when you reach out for help - while you're in the buying phase, they're very responsive - but as soon as you need support, you're looking at days not hours for a reply.
A special place in hell for APIs with multi-step setups for an access token (get jwt to get jwt which expires in few minutes but ofc cannot be renewed in advance), multi-step setups for a request envelope, then a cryptic payload, then polling (not too often!) for “ready” identifiers (which disappear once fetched, so please cache not-yours ones), then a separate request for fetching a response by identifier, deleted once fetched. Telcos and banks love this bullshit.
-
Building: needing to take various platforms and traditions into account (e.g. some php shops just don’t understand what long-poll or jsonl/ndjson streaming is and have a higher chance of hitting the auth wall for days). Webhook-based messaging requires valid domain names in development or setting up a complex local infrastructure. Overall boring prologues and epilogues for api calls in standard http libraries (try, rate, auth, parse params/body, validate, 2 lines of actual code, catch, decide if error is worth 500 or 4xx with a message, log details, report back). Testing with curl with auth/signing enabled just sucks.
Before this, I'd built https://bunnyapi.com which used a purely GET method.
Once you learn how to build an API, it's straightforward and not a pain at all. I use https://curlconverter.com/ to do the API which returns it in any language you need it in.
Then just read in the request, check the key if you have one, along with all the other instructions.
Building: the biggest pain is usually the language we are working in. the spec/protocol/etc don't matter, if they're popular they'll be supported in most languages. however, some languages just make building APIs hard-mode and annoying AF. even though I'm not the biggest fan of nodeJS anymore, building JSON apis with typecsript was a breeze compared to any other language. Have built both public REST and GraphQL apis.
A woodworking analogy: API's are the glue between applications, sometimes its a nice dovetail joint between the apps with a little glue and a lot of craftsmanship and things fit nicely. Sometimes it looks like Homer Simpson built it after a 12 pack of Duffs with glue all over the place and maybe a rusty bent nail holding things together. In the end it doesn't really matter since you are usually forced to integrate with an API so you just deal with the varying levels of quality.
Here are some things to not do (and how to deal):
- Error responses in HTML (have good handling for when JSON.parse fails)
- Missing/incorrect documentation on some endpoints (call the API and iterate to see how it responds)
- When changing API versions, change the ID of the things in the API (scripts to update old to new ID's, feature flag what ID to use, add yet another column to a table like v4_id)