Design: use-case vs object driven

[Mateusz Łoskot]

Hi,

This is my first post here, so hello everyone!
I'm an API rookie and I've started learning about Web API design with some projects of mine in mind.

I have browsed through the archives looking for some notes useful for a newbie in the API design business.
One of the interesting ones I found is this recommendation [1] by Mike Amundsen

"(...) as long as you design you API as use-case driven (GET /admin-dashboard) and not object-driven (GET /users/) (...)"

I admit, it is not as obvious to as it may seem.
Then, while reading the MuleSoft's "Secrets of a great API" whitepaper [2], I stumbled upon this "optimize for use case"
recommendation, to consider fine-grained vs coarse-grained functionality exposed by the API:

"Expose fine-grained services that users can access directly, and add coarse-grained services on top of them to
support broader use cases. Users can choose to call the fine-grained APIs directly or if they need the combined
functionality of multiple fine-grained calls they can use the coarse-grained APIs."

I think, directly relates to the use-case vs object driven approach mentioned by Mike.

Am I right there is a link between those ideas?
That is, use-case driven design makes coarse-grained APIs, while object-driven makes fine-grained APIs?

[1] https://groups.google.com/d/msg/api-craft/FQlLigU_n3E/YswTq7BPzK0J
[2] https://www.mulesoft.com/lp/whitepaper/api/secrets-great-api

Best regards,
--
Mateusz  Loskot, http://mateusz.loskot.net

[Irakli Nadareishvili]

Hello Mateusz,

coarse-grained is one aspect of the equation. In general, object- or entity- oriented APIs can be very limiting. Not everything lands itself in "Create, Update, Read and Delete". Classic exampled: if you are implementing a spell-checker - what is the object and which of the CRUD methods are you running? You can model spell-checker (and other such use-cases) with CRUD using imaginary, artificial "entities" but you will soon find yourself with a chatty, unnatural and awkward design.

Enough people have run into these issues that a lot of people now favor message-driven design over entity-oriented API design. In message-driven you look at a use-case and ask yourself: what is the message that a client needs to send the server to get what it intends done, what is the response the server needs to send back? That's it. Those messages may or may not contain some entities - doesn't matter. As for HTTP verbs: you use them as web Gods actually intended: considering their idempotence and safety features, rather than mapping them to CRUD.

I think the reason object-driven API design is popular is the same reason why ORMs were popular: easier to automate trivial cases. Much like with ORM, you can put yourself in very awkward corner with these automations when things pass trivial phase.

Hope this helps answer your question?

[Mateusz Loskot]

Hi Irakli,

Yes, your answer addresses my question very well.
It provides additional insights I've been looking for.

By the way, another angle I coudl relate to the granularity is about
issue of reflecting implemention details in representation design.
Such issue may often come from the fact of using serializers
ubiquitous in most of Web/API frameworks, which directly map
storage to representation.
Instread, deliberate choices should affect granularity in a good way.

It's well explained by Brian Sletten in REST API Design, starting at 39:00 min
https://www.youtube.com/watch?v=HW9wWZHWhnI

Regards,
Mateusz

> --
> You received this message because you are subscribed to a topic in the
> Google Groups "API Craft" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/api-craft/tk_gs7nLmvE/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> api-craft+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/api-craft.
> For more options, visit https://groups.google.com/d/optout.