Search code examples
restapifacebook-graph-apirestful-architectureapi-design

General vs Specific Endpoints - Restful API design


Is there any good reason why not to make a general endpoint for all resources, and/or to generalize all resources into one?

It seems like Facebooks Graph API is build that way. There is no /api/users, /api/companies, ect.. Or maybe it's just a general interface to talk to different resources on the server?

Obviously this approach can reduce alot of code replication on the backend if different resources have similar functionality.


Solution

  • Is there any good reason why not to make a general endpoint for all resources, and/or to generalize all resources into one?

    Yes -- but those reasons do not apply equally in all circumstances.

    When in doubt, review Chapter 5 of Fielding's dissertation.

    The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.

    With regard to resources in particular -- Ian Robinson covered some of this in his talk: The Counterintuitive Web

    Specialization and innovation depend on an open set.

    In RPC, the set of endpoints is closed, and the set of messages that can be sent to it is open. You innovate by creating new messages. In REST, the set of messages is closed, and the set of endpoints is open -- you innovate by creating new endpoints.

    An advantage in the latter approach is that you can use generic components to distribute the work, because they only need a limited understanding of a limited number of messages. For instances, caches don't need to understand the details and intent of your payloads to figure out what to do; they just need the identifier and some standardized meta data, and they are good to go.

    Now, taking GraphQL, there is a caching story. But do not overlook: that strategy isn't "oh, just plug in any commodity web cache".

    Horses for courses; this is a trade off, not a right/wrong dichotomy. If your project is so catastrophically successful that only the REST architectural constraints can save you, you've already handed the problem off to someone else and retired to your favorite tropical island.