#DEVDiscuss: API Designing

Time for #DEVDiscuss — right here on DEV 😎

Building Resilient Systems with Idempotent APIs

Karishma Shukla ・ Jul 28

#webdev #python #api #javascript

Inspired by @karishmashukla's Top 7 post, tonight’s topic is... API Designing!

Effective API design is essential for creating user-friendly, efficient, and maintainable software systems. Idempotency is just one aspect, so what elements of API design are most crucial to you and your team?

Questions:

• How do you handle versioning effectively?
• When it comes to error handling in APIs, what practices have you found most effective?
• How important is idempotency in your line of work?
• Any triumphs, fails, or other stories you'd like to share on this topic?

Comments

[nightwolfdev]

For a recent project, we used the OpenAPI spec. There are a lot of great tools out there to use with it.

[Thomas Bnt ☕]

Oh I used OpenAPI with Insomnia for one of my training project. It was a cool tool to show up all routes of the API.

[Fyodor]

So you follow the design-first approach? Could you please elaborate? What tools does you team use? How you handle matching the design and implementation? (Any checks/tools as well?)

[Liyas Thomas]

We are building an open source API development platform: Hoppscotch.

Meanwhile we're working on implementing API designing features, you can now manually test APIs and write tests to automate API testing either via web app or CLI.

You can organize APIs into collections and folders, share them with your team and follow best pratices.

hoppscotch / hoppscotch

👽 Open source API development ecosystem - https://hoppscotch.io

[Fyodor]

It’s hard to discuss the first three points to me ‘cos during the 10+ years in software on different sides of the barricades I didn’t see any ideal API with good versioning approach, consistent error handling with good coverage, or idempotency implemented reasonably and intentionally. So I believe for most businesses it’s not the highest priority or a topic to pay any attention to at all. Maybe just as a technical debt items 😅
So also hardy anything to call a triumph (I’m mostly a consumer, not a developer in terms of the APIs so my conscience is good thank you 😄).

As for failures I saw (and participated at partially unfortunately), the most obvious failure from my point of view is when you develop dev tooling APIs (sell shovels during golden rush so to speak) that help developers to build better APIs, and APIs of these tools themselves are not good and fail at meta checks. And that is all around, most of the tools suffer from that, especially in the rushing startup space.

[Nick]

I'm bad at writing APIs, even forgetting my own API parameters. Error handling is quite important to me, basically past me trying to remind myself what I was doing before. That means lots of checks at the start of the handler and being clear what part of my request was bad.