-3

Some years ago, every API I developed was a REST API and I did everything to follow the best practices to make them "RESTful".

But after some time, I have my doubts if RESTful APIs that should represent a Domain are not even an anti pattern.

The most important reasons:

  • The HTTP Methods like POST, PUT, DELETE and GET are often not expressive enough. For example a DELETE might be just a soft delete (setting a deleted flag to true), where its not clear which Method is the correct one (DELETE or PUT). Also those methods are promoting a CRUD like API design but usually the use cases in a domain are not matching CRUD.
    CRUD is not aligned with DDD.
  • The resource path design that RESTful APIs require is often not able to reflect the domain. For example a command (DDD) can affect many entities and its not possible to identify one "main" resource that should be addressed.
    Adding a user to a group for example affects two resources. So a RESTful route could be like:

PUT: api:/users/{userId}/memberships/{groupId}

or

PUT: api:/groups/{groupId}/members/{userId}

It seems not clear and the whole resource style becomes more and more a burden.
Not to think of more complex scenarios where three or four entities are affected.
For me a command style would be a lot more expressive like:

POST: api:/addUserToGroup  
Body: 
{
   UserId: 43,
   GroupId: 12
}
  • The HTTP status codes are not well defined. "Not found" for example should be used in HTTP if a route is not found. Not if a resource is not found.

My current idea is to just use two HTTP Methods: POST for commands and GET for queries and then build a CQRS API like design that represents my domain model a lot better.
All other methods like PUT or DELETE will not be used anymore.
My commands will be expressive domain commands and queries like:

  • AddUserToGroup POST
  • AddNewCustomer POST
  • RemoveProductFromCustomer POST
  • DeleteProduct POST
  • GetCustomersByFilter POST - but only because the filter object is in the body
  • GetCustomerById GET

But all giants like Microsoft or Google or Facebook design RESTful APIs and therefore I am hesitating to go my own way.

  • Whats wrong with my thinking?
  • Why are all APIs that I can think of are REST Apis?
  • Can you provide some book or blog article where those issues are addressed?
  • What are you doing?
Improve this question
16
  • 1
    "what's wrong?..." I think your approach is too dogmatic. REST is limited to HTTP verbs and has his flaws. You can either adapt or use another protocol, graphQL...
    – pdem
    Commented Sep 20, 2023 at 14:41
  • 1
    With REST, Roy Fielding described an API design approach that harmonizes really well with HTTP. REST isn't about URL structure, more about thinking about handling the state of resources in a server–client distributed system in a cacheable manner. Some HTTP features (like idempotent methods, etags) are really helpful here. But you're not forced to do HTTP in a RESTful style. You can use HTTP in a RPC style where URIs describe operations rather than resources, you just give up some of that REST–HTTP synergy. But if you go that route, you might as well use dedicated tools like gRPC or GraphQL.
    – amon
    Commented Sep 20, 2023 at 15:51
  • 3
    I'd say Roy Fielding's dissertation wasn't about design of service APIs at all. It was a high level description of the architecture of The Internet, the constraints that such a large scale system was subject to, and the idea of Representational State Transfer and HATEOAS, which is core to REST but is curiously ignored in what we call RESTfull services. What the industry calls the RESTfull style is very much a form of RPC - at least in contrast with what Fielding described as REST.
    – Filip Milovanović
    Commented Sep 20, 2023 at 16:19
  • 3
    BTW, here's a what Fielding himself had to say about this (it's a bit of a rant). Note that what he's really saying here is not that what the industry calls RESTfull APIs must be hypertext driven, but that RESTfull is only very superficially related to REST (the way he originally defined it). Which makes you wonder what else has been misunderstood and misappropriated, and which of the RESTfull practices are really sound, and which are based on wrong assumptions and flimsy justifications.
    – Filip Milovanović
    Commented Sep 20, 2023 at 16:36
  • 1
    @FilipMilovanović I actually think we should move away from the term 'REST' for this style and simply call them 'HTTP' APIs. But REST concepts are definitely informative in building good APIs. Sections 6.2 "REST Applied to URI" and 6.3 "REST Applied to HTTP" of Fielding's dissertation are helpful, including the 'mismatches' sub-section of each. But, as you note, this often doesn't have much to do with what people call 'REST' and I think it's often unhelpful to answering these kinds of questions.
    – JimmyJames
    Commented Sep 20, 2023 at 18:28

1 Answer 1

Reset to default
7

But all giants like Microsoft or Google or Facebook design RESTful APIs and therefore I am hesitating to go my own way.

Having worked at one of these places you mentioned, I can assure you that while Big Tech orgs often implement RESTful APIs, its not because we are dogmatic about its usage. We use the paradigm that best suites the use case, and the most common use case (this is purely anecdotal drawing from my personal experience, I don't have stats to back it up) often calls for RESTful APIs. But that doesn't mean these Big Tech orgs don't use and support other paradigms:

Alternatives to Consider:

  • GraphQL: Allows for more expressive queries and mutations.
  • gRPC: Uses HTTP/2 and Protocol Buffers, allows for more complex operations.
  • JSON-RPC or XML-RPC: These are protocol-agnostic and allow for more expressive commands.

Google has done a lot of work with gRPC and Protobuf:

https://github.com/protocolbuffers/protobuf

Facebook pioneered GraphQL:

https://engineering.fb.com/2015/09/14/core-data/graphql-a-data-query-language/

Microsoft provides good documentation on REST vs RPC for API design:

https://learn.microsoft.com/en-us/azure/architecture/microservices/design/api-design

REST versus RPC. Consider the tradeoffs between using a REST-style interface versus an RPC-style interface.

REST models resources, which can be a natural way to express your domain model. It defines a uniform interface based on HTTP verbs, which encourages evolvability. It has well-defined semantics in terms of idempotency, side effects, and response codes. And it enforces stateless communication, which improves scalability.

RPC is more oriented around operations or commands. Because RPC interfaces look like local method calls, it may lead you to design overly chatty APIs. However, that doesn't mean RPC must be chatty. It just means you need to use care when designing the interface.

For a RESTful interface, the most common choice is REST over HTTP using JSON. For an RPC-style interface, there are several popular frameworks, including gRPC, Apache Avro, and Apache Thrift.

"Building Microservices" by Sam Newman discusses some of these issues:

https://samnewman.io/books/building_microservices_2nd_edition/

In a nutshell, these big orgs try to be agnostic to the APIs paradigms that they try to implement and try to use what ever best suites the use case. Therefore, you should try to adopt a like mentality for your approaches too.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.