Any resources or advice for someone new to API design?

[rahhulk7]

As a newcomer to API design, I'm grappling with the differences between REST and GraphQL APIs. Specifically, the trade-offs between them are a bit confusing. Are there any recommended resources or general advice for beginners like myself trying to navigate API design choices?

[JustSteveKing]

API design is more of an artform than anything. GraphQL is great when you are perhaps using a noSQL database and the schema is somewhat fluid. However, if you have a relational database - you will get the best results using actual REST APIs.

The best way to think of an APIs design is; why do you need an API in the first place. Creating an API for the sake of having an API is what leads to terrible APIs. Instead design your API for its use case, and if you have multiple use-cases - maybe you need multiple APIs, or a more clever API design that blends well

[rahhulk7]

Thanks for the explanation! That makes sense to consider the database structure when choosing between REST and GraphQL. I hadn't thought about purpose-driven design before - focusing on the use case sounds key to avoiding bloated APIs. Do you have any favorite resources on designing for specific use cases?

Also, are there any tools that can help with documenting or visualizing different API design options?

[stop50]

For documenting APIs swagger is an standard that is widely used.

[DavorDK]

What kind of API are you looking to craft?