Web Services Design Checklist

From Guidance Share

Jump to: navigation, search


Design Considerations

  • The service exposes coarse-grained operations.
  • Entities used by the service are extensible and composed from standard elements.
  • Your design does not assume to know who the client is.
  • Your design assumes the possibility of invalid requests.
  • Your design separates functional business concerns from infrastructure operational concerns.

SOA Services

  • The services are application-scoped and not component-scoped.
  • The service interfaces are decoupled from the implementations.
  • The services have explicit boundaries.
  • The services are autonomous.
  • Service compatibility is based on policy.

Data Services

  • The service does not directly expose individual tables in a database.
  • The service does not implement business rules.

Workflow Services

  • The service uses interfaces supported by your workflow engine.
  • The service is dedicated to supporting workflow.


  • The service uses a suitable mechanism to securely authenticate users.
  • You have considered the implications of using different trust settings for executing service code.
  • Secure protocols such as SSL are used with basic authentication, or when credentials are passed as plain text.
  • Secure mechanisms such as WS Security are used for SOAP messages.


  • Appropriate access permissions for users, groups, and roles are set on resources.
  • URL authorization and/or file authorization are used when necessary.
  • Access to publicly-accessible service methods uses declarative principle permission demands where this is appropriate.
  • Services execute under the most restrictive account that is appropriate.


  • You have determined how to handle unreliable or intermittent communication scenarios.
  • Dynamic URL behavior is used to configure endpoints for maximum flexibility.
  • Endpoint addresses in messages are validated.
  • You have determined the approach for handling asynchronous calls.
  • You have decided if the message communication must be one-way or two-way.

Data Consistency

  • All parameters passed to the service components are validated.
  • All input is validated for malicious content.
  • Appropriate signing, encryption and encoding strategies are used for protecting your message.
  • XML schema is used to validate incoming SOAP messages.

Exception Management

  • Exceptions are not used to control business logic.
  • Sensitive information in exception messages and log files is not revealed to users.
  • Unhandled exceptions are dealt with appropriately.
  • You have designed an appropriate logging and notification strategy for critical errors and exceptions.
  • Tracing and debug-mode compilation are disabled for all services except during development and testing.

Message Construction

  • Appropriate patterns, such as Command, Document, Event, and Request-Reply are used for message constructions.
  • Very large quantities of data are divided into relatively smaller chunks and sent in sequence.
  • Expiration information is included in messages that are time-sensitive, and the service ignores expired messages.

Message Endpoint

  • Appropriate patterns such as Gateway, Mapper, Competing Consumers, and Message Dispatcher are used for message endpoints.
  • You have determined if you should accept all messages, or implement a filter to handle specific messages.
  • Your interface is designed for idempotency so that, if it receives duplicate messages from the same consumer, it will handle only one.
  • Your interface is designed for commutativity so that, if messages arrive out of order, they will be stored and then processed in the correct order.
  • Your interface is designed for disconnected scenarios, such as support for guaranteed delivery.

Message Protection

  • The service is using transport layer security when interaction between the service and consumer are not routed through intermediary servers.
  • The service is using message-based protection when interaction between the service and consumer are routed through other servers.
  • You have considered message-based plus transport layer (mixed) security when you need additional security.
  • Encryption is used to protect sensitive data in messages.
  • Digital signatures are used to protect messages and parameters from tampering.

Message Transformation

  • Appropriate patterns such as Canonical Data Mapper, Envelope Wrapper, and Normalizer are used for message transformation.
  • Metadata is used to define the message format.
  • An external repository is used to store the metadata when appropriate.

Message Exchange Patterns

  • You have chosen patterns that match your requirements without adding unnecessary complexity.
  • If you are using business process modeling techniques, your exchange patterns are not based on process steps, but instead support operations that combine process steps.
  • The service uses existing standards for message exchange patterns in order to provide a standards-based interface that can be understood by many consumers.

Representational State Transfer (REST)

  • You have used state diagrams to model and define resources that will be available to clients.
  • You have chosen an approach for resource identification that uses meaningful names for REST starting points and unique identifiers, such as a GUID, for specific resource instances.
  • POST operations are used only when necessary.
  • HTTP application protocol is used for common Web infrastructure like caching, ETags, authentication, and common data representation types.
  • You have designed the GET requests such that they return the same result when called.
  • You have designed your PUT and DELETE requests to be idempotent.


  • SOAP faults are used for returning errors instead of relying on default error-handling.
  • SOAP header block’s mustUnderstand attribute is set to “true” or “1”, of you want to force processing of the header block.
  • WS-* standards are used when possible.


  • All data received by the service interface is validated.
  • You have considered how the data will be used, such as whether data used in database queries will leave the database vulnerable to SQL injection attacks.
  • All trust boundaries are identified, and data that crosses these boundaries is validated.
  • You have determined whether validation that occurs in other layers is sufficient, or if you must validate it again.
  • The service returns informative error messages if validation fails.

Service Layer Considerations

  • Business rules are not implemented in the services layer.
  • Access to the service layer is defined by policies that allow consumers to determine the connection and security requirements, and other details related to interacting with the service.
  • Separate assemblies are used for major components in the service layer, such as the interface, implementation, data contracts, service contracts, fault contracts, and translators.
  • The service layer does not have or require knowledge of business entities used by the business layer.

Business Layer Considerations

  • Components in the business layer have no knowledge of the service layer, have no dependencies on code in the service layer, and do not execute code in the service layer.
  • A façade is used in the business layer to accept coarse-grained operations and break them down into multiple business operations.
  • The business layer is stateless in order to maximize the number of concurrent requests that the service can handle.

Data Layer Considerations

  • The data layer is deployed to the same physical tier as the business layer to reduce serialization requirements for objects that move across physical boundaries.
  • Access to the data layer does not use impersonation or delegation, instead it uses a common entity to access the data access layer while providing user identity information so that log and audit processes can associate users with the actions they perform.
  • Abstraction is employed in the design of the data access layer interface, probably by using the Data Access or Table Data Gateway pattern.
  • For simple CRUD operations, you have considered using a class for each table or view in the database, which represents the Table Module pattern.

Performance Considerations

  • Service contract operations are as coarse-grained as possible.
  • Business logic is not mixed with translator logic, and the service implementation is responsible only for translating data from one format to another.

Security Considerations

  • Used message-based security when requests are routed through other services.
  • Used transport layer security when requests are sent directly to the service.
  • You have considered using a combination of transport layer and message based security.
  • You have considered using message-based brokered authentication with X.509 certificates when designing Extranet or business-to-business (B2B) services.

Deployment Considerations

  • The service layer is deployed to the same tier as the business layer in order to maximize service performance.
  • You are using Named Pipes or Shared Memory protocols when a service is located on the same physical tier as the service consumer.
  • You are using the TCP protocol when a service is accessed only by other applications within a local network.
  • You are using the HTTP protocol when a service is publicly accessible from the Internet.
Personal tools