Systems are developed based upon a design framework. A service model is the separation between the interface and the implementation. The invoker of a service needs only to understand the interface; this allows the implementation to evolve over time without interruption of the service to the client. The benefits of service orientation derive from the abstraction of the delivery. The same interface can be offered in multiple implementations without affecting the application.
A service orientation views everything as a service provider. The service model is fractal in that a service can call any other service to implement its functionality. This includes both services which provide business functionality and nonfunctional services for logging, monitoring, data transformation, and so on. The newly formed process is a service itself; it exposes a new aggregated capability. Systems are developed to contain services; the services are programs which interact using well-defined message exchanges.
URIs are a main part of a web service interface. Once services have been published and used by internal and external clients, there will be difficulties in making changes.
The URI should be concise, easy to remember, and uniquely identify the target resource. The URL only should include nouns; it will need to identify the resource, not action.
HTTP Request Method implies action:
Versioning will need to be built into the services. Once services are published, it will be difficult to introduce versioning. If a new release of services is not backward compatible, then it probably will be necessary to maintain two versions during the period of client upgrade. A client will need to pass version information in the 'Accept' request header that the server can use. In the event, that the version passed is unsupported, the server will need to respond with HTTP Response Code 415 and an accompanying message.
Services should be granular. Services typically will map to top level domain objects. In a well designed domain model, operations on top level domain objects will map to business use cases.
Exposing each persistent object using a web service is not a recommended practice. It exposes internal application design, adds redundant and unused services and makes service difficult to understand and use.
Request/Response Mime Types
Service should use standard HTTP headers to consume and produce different mime types. New content types then can be supported without changing service interface. Content-type header of the request determine the type of the content service to expected and accept header of the request will determine the type of response body that services produce. The typical content-type and accept headers will be: application/xml and application/json.
Client-specific operational requirements and performance objectives are taught:
Services should cache only successful GET requests. Caching at multiple layers is needed to have good performance. Persistent layer caching is important. Method level caching can be added. Services also should include a cache-control header in the response, this will allow the client to cache the response.
For cacheable responses, server should set HTTP 'Vary' header to indicate that the response is cacheable based on the URL plus the returned Content-Type: Vary as follows: Vary: Content-Type.
Logging should be based on one log per request pattern. In a multi-user environment, it will be useful in problem resolution to have one log per request. All logs for the request can be accumulated in request thread and printed once at the end of the request.
1. Service should apply HTTP Status Codes for communicating success and failure that can be used by program clients. It might be necessary to add Custom HTTP Status Codes for specific use case. However, this should be kept to a minimum. Contextual information about an error should be included in reason phrase of HTTP response or custom HTTP response headers.
2. Service requests involving user entered data with POST and PUT should include a list of user error messages in the response body to correct the error condition. Adding a new custom HTTP Status code (450) will communicate the user data validation error to the client.
The document should include for each service method:
WebSphere and Rational are registered trademarks of IBM Corporation.
Java is a registered trademark of Sun Microsystems, Inc. and Oracle America, Inc.