Value of Service Interfaces

January 4, 2015

Wrote earlier about why interfaces are important and in this post want to elaborate on their advantages for building reusable services. Service interfaces contain only the operation or method definitions and have no implementations. They can be used in a variety of ways:

  • Package service interfaces into a separate artifact to make it easy for client teams to integrate with services without pulling in bulky set of transitive dependencies
  • Bind the interfaces to one or more transport / integration technology via standard Dependency Injection (DI). For example, service interfaces can be integrated with a REST-ful Resource or a EMS listener.
  • Service interfaces can be backed by stub and/or mock implementation for automated unit and regression testing.
  • Service interfaces can be decorated with common cross-cutting concerns to separate them from the implementation. This is the strategy implemented via the Java Dynamic Proxy example.
  • Service interfaces can be implemented as a proxy to a remote implementation. For example, the client invokes the functionality via the interface but the runtime implementation makes a call to a server side API. This is useful if your teams need the flexibility to swap local / remote implementations depending on performance / dependency management related requirements
Advertisements

Tips When Authoring Web Service Clients

November 3, 2013

Here are some tips when authoring web service clients:

  1. Decouple connectivity from request construction. This will isolate variations in input construction and the mechanics of service invocation cleanly separated. Additionally, the request construction might depend on the particular resource – e.g. they can be set of query string parameters or a more complex object structure.
  2. Connectivity logic should encapsulate the service URL and automatic-retry considerations. The client can automatically retry GET requests specified number of times if invocation encounters a connection timeout. It should also ensure response is OK (either via HTTP status codes or by examining appropriate response-specific data structures).
  3. Don’t swallow exceptions – the service might return a resource not found or an internal server error – the code that is using the client should be given the flexibility to deal with these exceptions appropriately – the client code shouldn’t assume or mask these exceptions. When in doubt, don’t suppress runtime exceptions.
  4. Decouple domain logic from service client – domain logic might dictate whether or not a service call needs to be made, or the nature of input resource data, etc. – this logic is more likely to change per the consuming application’s evolving requirements and shouldn’t be hosting service invocation code in the same class.
  5. Provide reusable API hooks for addressing cross-cutting concerns – such as response time capture and input and output messages – if you want to report response time trends when invoking a service you will not want to clutter this all over the consuming application’s codebase – the client can and should centralize these.

Remember the above is useful whether you are consuming a service or providing clients for your prospective service consumers.


Client Integration Mini-Checklist for Services

May 27, 2012

Working with clients who are consuming your services? Here is a mini-checklist of questions to ask:

  1. While executing request/reply on the service interface is there a timeout value set on the call?
  2. Is there code/logic to handle SOAP Faults /system exceptions when invoking the service?
  3. Is building service header separated from the payload? This will facilitate reuse across services that share common header parameters
  4. If there are certain error codes that the calling code can handle, is there logic for each of them?
  5. Is the physical end point information (URL string for HTTP, Queue connection and name for MQ/EMS) stored in an external configuration file?
  6. Is UTF-8 encoding used while sending XML requests to the service i.e. by making use of platform-specific UTF encoding objects?
  7. If using form-encoding are unsafe characters such as ‘&’, ‘+’, ‘@’ escaped using appropriate %xx (hexadecimal) values?
  8. While processing the service response is the logic for parsing/processing SOAP and service-specific headers decoupled from processing the business data elements?
  9. Is the entire request/reply operation – invocation and response handling logic – encapsulated into its own class or method call?
  10. While performing testing, is the appropriate testing environment URL/queue manager being used?
  11. Is a valid correlation id being used in the service request? This is very essential for aynchronous request/reply over JMS (JMS Header) or HTTP (callback handler)

Software Reuse Quick Tip #26

July 10, 2010

Tip #26 – Build Reusable Services

The following are useful tips when designing and implementing reusable services.

Expose only logical data attributes and “standardized” values to external consumers in the service contract. This will ensure that the data service has maximum flexibility to change physical system implementations underneath and the consumer will not be adversely impacted.

Reuse business object schemas across data service operations and while preparing WSDL documents. This will ensure logical data model alignment as well as consistent definition of business objects simplifying consumption and maintenance effort.

Expose event driven publication services for data propagation to downstream consumers using standard publication messages. This will greatly reduce (and potentially eliminate) the need for source specific messages and needless data transformations. Standard publication messages could be versioned and new consumers could be added via configuration on a messaging broker without requiring development effort.

Provide multiple flavors of services based on commonly used use cases for the data service. A light flavor of a service will be useful for clients who do not want to parse a large business object message returned by the full flavor.

Strive for abstraction of data source specific semantics in order to insulate the consumer from physical data source processing/logic. This practice applies to identifiers, data values, data structures, and data orchestration logic that could be coupled to a physical source if proper care isn’t taken.

Prefer reliable transports when invoking data services asynchronously. Although it is possible to simulate asynchronous processing using transport protocols such as HTTP it is not advisable to do so. In the event the data consumer becomes unavailable messages are lost.


10 Design Assumptions That Hurt Your SOA Efforts

August 24, 2009

Building service capabilities that are strategic for your enterprise is a key aspect of SOA and lays the foundation for agile business processes in your organization. Many teams are engaged in building service capabilities both as part of SOA initiatives and bottom-up ones motivated by technology teams pursuing the benefits of service orientation.

How do you ensure that the service capabilities are in line with business objectives?
Are th
ere assumptions that hurt your SOA? I believe so! Here are 10 design assumptions that you need to watch out for:

  1. Service capabilities are always Web Services
  2. Services need to support only one data format i.e. SOAP
  3. Services are implemented first and then contracts are extracted (aka code-first approach)warningsign
  4. Service contracts don’t have to be reviewed or governed
  5. Service capabilities from vendor solutions can be consumed out of the box without mediation
  6. Services handle exceptions in an ad-hoc manner
  7. Services implement consumer specific logic
  8. Service interfaces are always non-validating
  9. Service capabilities are always accessed in a on-demand fashion. No need to support event driven interactions.
  10. Service consumers will all migrate to new versions simultaneously. No need to support multiple versions.

Please add to this list any additional assumptions that inhibit the effectiveness of SOA efforts!

Like this post? Subscribe to RSS feed or get blog updates via email.

add to del.icio.us: Digg it : post to facebook: Stumble It! : :


Building Strategic Services – Article Published

July 18, 2009

soaworld

Article on Building Strategic Services was recently published by SOA World Magazine. The article covers various best practices and techniques relevant to service orientation and service delivery.

Like this post? Subscribe to RSS feed or get blog updates via email.

add to del.icio.us: Digg it : post to facebook: Stumble It! : :


Building services for Reuse – Top 10 Practices for your SOA

May 1, 2009

You want to build services that are reusable across projects and initiatives. That is the aspiration at least. How do you make sure that your services are reusable? Here is my top 10 list to achieve this goal:

  1. Make sure your services are interoperable across platforms. What do i mean by this? you don’t want platform specific data structures, parameters, header values, etc. in your service contract. You also want to use a tool like WSDL Analyzer to ensure that your interfaces are compliant with Web Services Interoperability guidelines.
  2. Minimize (if possible avoid) building services specific to a target consumer -whether it is a process, human, or an external application. When you build point solutions you are not building reusable ones!
  3. Decouple transport logic from services logic. You don’t want your service to be only available via HTTP. Most enterprises that need guaranteed delivery, scalability, and asynchronous processing will want your service to be accessible via a reliable messaging transport such as JMS. So don’t make your service tightly coupled with a transport
  4. Avoid naming schema elements after particular systems or technologies. Your element names and complex data types should be domain relevant  and be descriptive. e.g. don’t use names such as MyEntity or customer001!
  5. Separate authentication from core services logic – you want to decouple the core services logic from how you authenticate the service request. This will give you the flexibility to support multiple authentication mechanisms (e.g. for a real time invocation the authentication might be a userid/encrypted password vs. a messaging invocation could be based on authentication set on a particular queue) or switch technologies altogether (e.g. change authentication from using LDAP tokens to X509 certificates).
  6. Encapsulate data object so they can use a separate schema: You don’t want to mix web method or service interface level elements with data object related elements. If you keep these separate, it will facilitate reuse of data objects across services (e.g. getCustomer and updateCustomer could both use a Customer data schema definition).
  7. Reuse data types across schema contracts – You should always be consistent with types within your domain and your organization across conracts. A customer name or gender cannot have one set of definitions in one schema and a different one in another schema. Reuse of complex data types will be tricky and you might be forced to use a custom definition on each instance but you can at least adopt this practice for simple data types.
  8. Design services to support multiple access patterns – This practice is essential for services that need to be accessed in both real-time and an event driven fashion. For instance, you have a getCustomer service capability that can be accessed on-demand as well as for publishing updates to customer data for a set of interested parties.
  9. Keep your service capabilities stateless – Avoid complex web of calls to manage state and keep your interface stateless. Sure it will make the interface bulkier but it is far easier to reuse a stateless service than a stateful one!
  10. Publish standard events from your business processes – Don’t build point to point integrations with downstream systems that need notifications from your business processes. Instead for each business process support a standard list of events you will publish. Any interested party can subscribe to the standard events and act accordingly to consume.

If you have additional practices and design techniques please contribute!

Like this post? Subscribe to RSS feed or get blog updates via email.

add to del.icio.us: Digg it : post to facebook: Stumble It! : :


%d bloggers like this: