DEV Community

Cover image for #DEVDiscuss: API Designing
Brian Bethencourt for The DEV Team

Posted on

#DEVDiscuss: API Designing

Time for #DEVDiscuss β€” right here on DEV 😎

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?

Top comments (6)

Collapse
 
nightwolfdev profile image
nightwolfdev

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

Collapse
 
thomasbnt profile image
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.

Collapse
 
fyodorio profile image
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?)

Collapse
 
liyasthomas profile image
Liyas Thomas • Edited

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.

GitHub logo hoppscotch / hoppscotch

πŸ‘½ Open source API development ecosystem - https://hoppscotch.io

Collapse
 
fyodorio profile image
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.

Collapse
 
fleker profile image
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.