A web service is an API over HTTP (using SOAP, REST, or GraphQL). An API is a contract between two pieces of software. A microservice is a deployable unit with a single responsibility. The right answer is to pick the boundary based on the team’s deploy frequency, the data ownership, and the failure isolation need. The mistake every team makes is to call everything a ‘microservice’ and end up with a distributed monolith — multiple services that must deploy together, share a database, and have the same failure mode.
Table of contents
- The web service — the HTTP API
- The API — the contract
- The microservice — the deployable unit
- The right boundary for each use case
- The transport — REST, GraphQL, gRPC, message queue
- The data ownership — who owns the database
- How this fits the rest of the stack
- FAQ
The web service — the HTTP API
A web service is an API that runs over HTTP. The most common forms are REST (with JSON payloads), GraphQL (with a single endpoint and a query language), and SOAP (with XML payloads, less common in 2026). The right answer is REST for a simple CRUD API, GraphQL for a flexible client-side data fetching, SOAP only for legacy enterprise integrations.
The gotcha: every web service is an API, but not every API is a web service. An API can use any transport (gRPC over HTTP/2, message queues, in-process calls). The right answer is to pick the transport based on the team’s use case, not the name.
The API — the contract
An API is a contract between two pieces of software. The contract defines what the client can ask for, what the server returns, and what the failure modes are. The right answer is to design the API as a contract first, then implement the server. The wrong answer is to implement the server first, then write the API docs from the implementation — the contract drifts from the implementation, the client breaks.
The contract can be expressed as OpenAPI (for REST), GraphQL SDL (for GraphQL), or a Protocol Buffers file (for gRPC). The right answer is to commit the contract to the repo, generate the client and server stubs from the contract, and version the contract (SemVer) so the team can evolve the API without breaking clients.
The microservice — the deployable unit
A microservice is a deployable unit with a single responsibility. The service owns its data, the service has its own pipeline, the service can be deployed independently of other services. The right answer is a microservice for a team that needs to deploy the service independently of the rest of the system, that has a clear data ownership boundary, and that has a different scaling profile from the rest of the system.
The gotcha: every microservice is a web service, but not every web service is a microservice. A web service that shares a database with other services, that must deploy together with other services, and that has the same scaling profile is a distributed monolith, not a microservice. The right answer is to name the boundary correctly so the team’s mental model is right.
The right boundary for each use case
The right answer is a function of the team’s context:
- Monolith with no scaling concerns — start with a single deployable unit, extract services as needed.
- Web service with a clear API boundary — start with a REST or GraphQL service, treat it as a single deployable unit.
- Microservice with independent scaling and deploys — extract the service to its own deployable unit, with its own database, its own pipeline, and its own observability.
- Distributed monolith — multiple services that share a database and must deploy together. The right answer is to fix the coupling (give each service its own database) or to admit it’s a monolith and deploy as one.
The right answer for a team that is starting a new project is a monolith, not microservices. The right answer for a team that is splitting an existing monolith is to extract the service that has the clearest boundary, the most different scaling profile, or the most independent deploy frequency.
The transport — REST, GraphQL, gRPC, message queue
REST is the right answer for a simple CRUD API, a public API, or a team that wants the broadest client support. The right answer is REST for an API that returns resources, has a clear URL structure, and uses HTTP verbs for the action.
GraphQL is the right answer for a flexible client-side data fetching, a team that wants the client to control the response shape, or a team that has multiple clients with different data needs. The wrong answer is GraphQL for a simple CRUD API — the team is paying for the GraphQL runtime overhead for a use case REST handles better.
gRPC is the right answer for service-to-service communication in a microservices system, for a team that wants typed contracts, or for a team that needs high-performance streaming. The wrong answer is gRPC for a public API — gRPC’s tooling is web-unfriendly, and the team will end up building a REST gateway anyway.
Message queue (RabbitMQ, Kafka, SQS) is the right answer for asynchronous communication, for a team that wants to decouple the producer from the consumer, or for a team that needs to buffer bursts. The wrong answer is a message queue for a synchronous request-response — the team’s latency is the queue’s latency, and the team’s mental model is wrong.
The data ownership — who owns the database
The right answer for a microservice is that the service owns its data. The team that has multiple services sharing a database has a distributed monolith — the services are coupled at the data layer, the team’s migrations must be coordinated, the team’s data consistency is the team’s problem.
The right answer is one service, one database, one schema. The service exposes its data through its API, other services consume the data through the API. The wrong answer is to share a database for performance reasons — the team is paying for the data consistency complexity, not getting the performance benefit.
How this fits the rest of the stack
The infrastructure question is a small piece of a larger pattern: the team’s runtime, storage, database, secret store, logs, and deployment platform are all parts of the same platform. The right answer is to model the full stack before the project ships, not after. The RunxBuild hosting calculator is the right place to do that exercise — pick the runtime, the memory tier, the storage, the secret store, and the egress, and the calculator shows what the deploy actually costs at the team’s actual usage.
Useful related references:
FAQ
What is the difference between a web service and an API?
A web service is an API that runs over HTTP. An API is a contract between two pieces of software, using any transport.
What is the difference between a microservice and a web service?
A microservice is a deployable unit with a single responsibility and its own data. A web service is the API over HTTP, regardless of the deploy model.
What is a distributed monolith?
Multiple services that share a database and must deploy together. The services are coupled at the data layer, the team’s migrations must be coordinated, the team’s data consistency is the team’s problem.
When should I use microservices?
When the team needs to deploy services independently, when the data ownership boundary is clear, and when the scaling profile is different for each service. The right answer is to start with a monolith, extract services as needed.
What is the difference between REST and GraphQL?
REST is a resource-based API with HTTP verbs. GraphQL is a query language with a single endpoint and the client controls the response shape.
When should I use gRPC?
For service-to-service communication in a microservices system, for typed contracts, or for high-performance streaming. The wrong answer is gRPC for a public API — the team will end up building a REST gateway.
When should I use a message queue?
For asynchronous communication, for decoupling the producer from the consumer, or for buffering bursts. The wrong answer is a message queue for synchronous request-response.
What is the right transport for a public API?
REST or GraphQL. The right answer is REST for a simple CRUD API, GraphQL for a flexible client-side data fetching.