When designing an API, choosing how to structure endpoints and model the interaction between client and server is a critical design decision. The three alternatives outlined – data-driven, object-oriented, and action/process-driven – represent different approaches with distinct strengths and weaknesses. The choice of approach should be based on both technical and business needs, as well as user expectations and workflows.

1. Data-Driven Approach

Description

This approach focuses on data as the primary entity in the API. Clients perceive the API as a system for storing and retrieving data, without directly interacting with actions or processes. Business logic and processing happen invisibly on the backend, and clients only see the results through the data produced.

Characteristics

• Clear separation between data and processes.
• Clients interact only with resources (e.g., submissions) and their lifecycle.
• Process statuses are represented as fields in the data.
• Resembles a CRUD (Create, Read, Update, Delete) approach.

Advantages

• Simple for clients – they only retrieve and store data without needing to understand domain logic.
• Fewer endpoints with a consistent URL structure.
• Well-aligned with REST principles.

Disadvantages

• Business logic can be difficult for clients to understand and discover.
• Risk of logic being spread across clients if the API does not provide enough guidance.
• Less suitable for complex processes involving multiple steps or data types.

Example

GET /data/submission
GET /data/submission/1199930
POST /data/submission
PATCH /data/submission/1199930

When is this approach suitable?

• For simple systems where processes are not highly complex.
• When clients primarily work directly with data (e.g., case handlers).
• When minimal coupling between clients and domain-specific business logic is desired.

2. Object-Oriented Approach

Description

In this approach, each resource is treated as an object that has both data and associated operations (methods). Clients can not only retrieve and update data but also trigger specific actions on each resource. This makes business logic more explicit in the API.

Characteristics

• Each resource has its own set of operations/actions.
• Clients must understand domain-specific concepts and processes.
• The approach resembles object-oriented systems, where objects have methods.

Advantages

• Clearer process support – clients receive explicit signals about available actions.
• Easier for clients to navigate business logic.
• Well-suited for resources with many specific actions governed by business rules.

Disadvantages

• Can lead to an explosion of endpoints when multiple resources have multiple actions.
• Maintaining a consistent structure across various object types can be challenging.
• Can become cumbersome if many actions are not resource-specific but apply across multiple resources.

Example

POST /data/submission/search
POST /data/submission/submit
POST /data/submission/1199930/selectPractice
POST /data/submission/1199930/cancel

When is this approach suitable?

• When resources have specific, business-related operations.
• When it is important for clients to understand the processes around resources.
• When the API is part of a larger domain application with domain-oriented users.

3. Action/Process-Driven Approach

Description

This approach explicitly separates actions from data. Clients retrieve and manage data in one way, while business processes and operations are modeled as separate process resources or services. This allows actions to involve multiple data types simultaneously and handle more complex workflows.

Characteristics

• Clear distinction between data and processes.
• Processes have dedicated endpoints that handle multiple resources and complex logic.
• Suitable for larger, cross-cutting processes.
• Often inspired by Command-Query Responsibility Segregation (CQRS).

Advantages

• High flexibility in modeling business logic.
• Easier to version or modify process logic without changing data models.
• Well-suited for systems with complex, multi-step workflows.

Disadvantages

• Can create uncertainty about which data the processes operate on.
• Requires more documentation and client adaptation.
• May result in an artificial separation of data access and process handling, even when logically connected.

Example

POST /process/submitReimbursementClaim
POST /process/updateReimbursementClaim
POST /search

When is this approach suitable?

• When processes involve multiple different data types.
• When processes have high complexity and multiple steps.
• When processes should function as “black box” operations with clear input and output.
• When supporting both manual and automated workflows via the same interface.

Summary Evaluation

Recommendation

Choosing an approach should be based on:

• The complexity of the domain.
• How self-sufficient clients need to be.
• How clearly processes need to be defined for clients.
• Whether the API is primarily a CRUD interface or a process-driven system.

In many cases, a hybrid model may be the best solution, where basic data is managed using a data-driven approach, while more complex workflows are exposed via process-driven endpoints. This provides both simple data handling and flexible process support.