Development/AWS

Do RESTful APIs Always Have to Follow the Textbook?

kozylife 2025. 8. 20. 20:09

Insights from Maintaining Legacy Systems While Comparing REST vs RPC

I was designing APIs for a new project when it happened. We were adding v3 to a system that had been running with POST /listUser style endpoints since v1 and v2.

 

Naturally, I followed the existing pattern and went with RPC-style design. But throughout the development process, one thought kept nagging at me: "What would this look like if we had designed it as a RESTful API?"

 

It's a situation every developer faces. You have an established direction, but you can't help wondering about alternative approaches. Even when you need to maintain consistency with existing systems, curiosity about new methodologies never really goes away.

 

Through this post, I want to objectively compare RESTful APIs with RPC-style APIs and share the insights I gained while maintaining our existing approach.

Revisiting RESTful APIs from the Textbook

Let's start by briefly reviewing what RESTful APIs are all about. REST (Representational State Transfer) is an architectural style that maximizes the advantages of the web, built on three core components:

 

1. Resources (Nouns) These represent the entities your API manages - users, products, orders, and anything else you're working with. Examples: users, products, orders

 

2. Actions (Verbs) Operations performed on resources, expressed through HTTP methods. GET: Retrieve POST: Create PUT: Update DELETE: Remove

 

3. Representations The data format representing the state of resources, typically JSON. Here's what this looks like in practice:

GET /users          # Retrieve user list
GET /users/123       # Retrieve specific user
POST /users          # Create new user
PUT /users/123       # Update user information
DELETE /users/123    # Delete user

Clean and intuitive. You can tell what each endpoint does just by looking at it, and it aligns perfectly with HTTP's fundamental philosophy.

My Real-World API: The RPC Style

But the API I actually built looked a bit different:

POST /listUser           # Retrieve user list
POST /getUserDetail      # Retrieve specific user details
POST /createUser         # Create new user
POST /updateUser         # Update user information
POST /deleteUser         # Delete user

This approach is called 'RPC (Remote Procedure Call)' style. As the name suggests, it's about remotely calling specific functions on the server. You design APIs like calling local functions - listUser(), getUserDetail(), and so on.

The Rational Reasons for Sticking with RPC

1. System Consistency First

The most important consideration was consistency with existing versions. We'd been running v1 and v2 with RPC style for years, and dozens of client companies were already familiar with this pattern. Suddenly switching to RESTful in v3 would have caused unnecessary learning costs and confusion for existing users.

 

In API design, consistency is just as important as technical perfection. When considering user experience continuity, maintaining the existing approach was the more rational choice.

2. Client Intuition

Another advantage of the RPC approach was its intuitive nature. For our client companies, POST /listUser was clearer than GET /users. They could immediately understand "this API fetches user lists" just by looking at the function name.

 

Especially for developers new to APIs, explaining "this endpoint retrieves users" was much more straightforward than diving into the semantic differences of HTTP methods.

Head-to-Head Comparison: RESTful vs. RPC

Let's objectively compare both approaches.

Design Philosophy Differences

RESTful API

  • Resource-centered, noun-based design
  • Actively leverages HTTP's fundamental philosophy
  • Endpoint examples: /users, /users/123

RPC-style API

  • Action-centered, verb-based design
  • Intuitive naming like function calls
  • Endpoint examples: /listUser, /getUserDetail

HTTP Method Usage

RESTful API

  • Actively utilizes the meaning of HTTP methods like GET, POST, PUT, DELETE
  • You can infer the operation just from the method
  • Aligns well with web standards

RPC-style API

  • Primarily uses POST and GET
  • Relies on endpoint names rather than methods
  • Freedom from semantic constraints of HTTP methods

Strengths of Each Approach

RESTful API Advantages

  • Standardized and predictable structure
  • Easy to leverage web infrastructure like caching and CDNs
  • Great long-term scalability and maintainability
  • Familiar web standards for developers

RPC-style API Advantages

  • Intuitive and easy to learn
  • Can handle complex business logic in single requests
  • Aligns well with functional thinking
  • Great for rapid development and prototyping

Limitations of Each Approach

RESTful API Challenges

  • Initial learning curve exists
  • Difficult to express complex actions or transactions
  • Sometimes forces awkward mapping to resources

RPC-style API Challenges

  • Endpoints can grow exponentially
  • Difficult to maintain consistency (naming conventions, etc.)
  • Limited use of HTTP caching mechanisms

When to Use Which?

RESTful API Works Best For

  • Public APIs or services with lots of external integrations
  • Large organizations that prioritize standards
  • Projects where long-term scalability is crucial
  • Systems accessed by diverse clients

RPC-style API Works Best For

  • Internal microservice communication
  • Projects where quick and simple development is priority
  • Cases where consistency with existing systems matters
  • Applications with complex business logic

Conclusion: Insights from Comparative Analysis

Maintaining our existing approach while comparing it with RESTful APIs yielded several important insights.

 

Our team's decision to stick with RPC style was a rational choice that prioritized system consistency and user experience continuity. Through this process, however, I gained a clear understanding of each approach's strengths and weaknesses, and I can see making different choices for future projects depending on the situation.

 

The most important realization was that there's no 'absolute right answer' in technology choices.

 

What matters most is clearly understanding the trade-offs of each approach and making the optimal decision for your project's context.

  • What's your team's technical proficiency level?
  • What's the background knowledge of your users?
  • How important is compatibility with existing systems?
  • What are your long-term expansion plans?

The answers to these questions should guide your technical choices.

 

If you're currently comparing API design approaches, I hope this post provides some useful perspective. Most importantly, remember that "just because it's different from existing systems doesn't mean you have to change it."