Web Services Design Checklist

From Guidance Share

Contents 1 Design Considerations 2 SOA Services 3 Data Services 4 Workflow Services 5 Authentication 6 Authorization 7 Communication 8 Data Consistency 9 Exception Management 10 Message Construction 11 Message Endpoint 12 Message Protection 13 Message Transformation 14 Message Exchange Patterns 15 Representational State Transfer (REST) 16 SOAP 17 Validation 18 Service Layer Considerations 19 Business Layer Considerations 20 Data Layer Considerations 21 Performance Considerations 22 Security Considerations 23 Deployment Considerations

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.

Authentication

• 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.

Authorization

• 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.

Communication

• 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

• 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.

Validation

• 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.