# Service granularity principle

In the context of software engineering and software architecture, service granularity is a key design concern when applying the paradigm of service-orientation for instance during service-oriented modeling. Service granularity specifies the scope of business functionality and the structure of the message payload in a service operation that is provided within a service-oriented architecture (SOA).

## Definition

Service granularity is both an application domain concern (business granularity), as well as a software interface design issue (technical granularity); it is a property of the service contract exposed by a service provider. It pertains to the semantics and syntax of the in (request) and out (response) message content, which can be viewed as instances of two general Enterprise Integration Patterns, Command Message and Document Message. By definition a coarse-grained service operation has broader scope than a fine-grained service, although the terms are relative. The former typically requires increased design complexity but can reduce the number of calls required to complete a task.

## Criteria

Due to the fallacies of distributed computing, finding an adequate granularity is hard. There is no single simple answer but a number of criteria exist (see below). A primary goal of service modeling and granularity design is to achieve loose coupling and modularity, which are two of the essential SOA principles, and to address other architecturally significant requirements.
Many forces influence the service granularity; four particularly relevant factors to consider when designing for an adequate granularity are performance, message size, transactionality and business function:

### Business function

Ideally, each service operation maps to a single business function, although if a single operation can provide multiple functions without adding design complexity or increasing message sizes, this generality can reduce implementation and usage costs.

### Performance

Web services are accessed remotely and calls to web service operation create more network overhead. Reducing the number of service requests reduces that overhead.

### Message size

Coarse-grained services may pass more data than fine-grained services, including data that is not specifically required for the task. This complicates message processing in the endpoint and might in turn harm performance. Reducing message size may require adding a more fine-grained operation.

### Quality-of-service characteristics including transactionality

For conceptual clarity each service operation should perform a single system-level transaction and leave data integrity across service boundaries to the business logic in the service consumer. This also simplifies error recovery, and typically eases design.
Many more decision criteria for finding an appropriate granularity exist; there is no global optimum. Sixteen such coupling criteria are compiled from the literature in.

## Patterns

As one size does not fit all, the design of service granularities can benefit from many existing pattern works on various kinds of distributed systems, especially those related to services, as well as pattern works related to API design (e.g., API design in object-oriented programming) and enterprise integration. An overview of such languages is given here.