Web service Interface design

http://www.ibm.com/developerworks/architecture/library/ar-servdsgn1/

 

Best practices for service interface design in SOA, Part 1: Exploring the development, interfaces, and operation semantics of services

 

http://www.ibm.com/developerworks/architecture/library/ar-servdsgn2/#fig1

Best practices for service interface design in SOA, Part 2: Using services to report errors to service consumer applications

 

(1)Best practice: If related information resides on multiple EISs, you should first define physical system-specific interfaces grouping information type-related transactions, and then aggregate these interfaces into a single interface.

 

(2)Best practice: When designing a new service, do not mix synchronous and asynchronous invocation semantics in a single interface (WSDL port type). If it is advantageous to support both semantics, define separate interfaces for synchronous and asynchronous invocations.

 

(3)Best practice: Design your service interfaces for stateless interactions. The request message passed in to the operation should contain all information necessary to complete that operation, regardless of the sequence in which other interface operations are invoked.

 

(4) Best practice: Define and use custom headers to carry system-relevant information that is specific to your business or project. Avoid putting system-relevant information into the body of your message.

 

(5) Best practice: For synchronous architectures with request-response operations, define both system and business faults in your operation signature. System faults and business faults should be described by different XSD types.

 

(6)Best practice: A fault message should contain a single WSDL part. The value of this part is a complex XSD type containing a complete description of the error.

 

(7)Best practice: Fault messages should contain an error code that allows the service consumer applications (clients) to process errors programmatically. Error codes should be published as an integral part of the WSDL service definition to make it easier for service consumer applications to understand the meaning of reported errors.

 

(8)Best practice: For request-response operations that don't involve batch processing, use WSDL faults to return error information from your service interface to service consumer applications, rather than return error information in the response message and status code.

 

(9)Best practice: When invoking Web services, catch all declared faults and handle system and business errors in separate catch blocks.

 

(10)Best practice: While catching system and business errors, also catch the base error type java.lang.Throwable to deal with any unexpected error conditions raised by the client stack.