Beautiful REST API documentation

InfoQ has published a list of tools that can be used for creating some cool documentation for our Web APIs.

I was particularly impressed with Swagger and the demo available here.
RAML from MuleSoft was also quite interesting. The list of projects available for RAML makes it a serious candidate for documenting our REST APIs. 

Taxonomy of Services

In one of my previous posts, I had blogged about creating a taxonomy of services using functional categorization.
For e.g. Entity Services, Task/Activity Services, Process Services and Infrastructure services.

But services can also be categorized from different perspectives such as layers or intent of use. For e.g.
Categorization based on Service Layer:

1. Business Services: Represent high level business functions that define an enterprise.
2. Application Services: Application specific and usually will be aggregated in a composite service at the business level.
3. Infrastructure Services: Utility functions that deliver cross cutting functions.

Categorization based on scope:
1. Enterprise Services: Multiple LOBs use the service.
2. Domain Services: Applicable only within a LOB.
3. Application Services: Local to the App Level.

Oracle Web Service Manager vs Oracle Enterprise Gateway

Oracle Web Service Manager is an integral part of the Oracle SOA suite and it allows us to implement security declaratively; without any coding from the developer. Security policies can be enforced at run-time using WSM agents or WSM gateways.
There is another product called "Oracle Enterprise Gateway" that has features that overlap with OWSM - hence this results in lot of confusion.

So, lets understand the concepts one by one. A WSM agent is a component that is installed with the endpoint service. So it provides the 'last-mile' security (last security layer). Now OWSM also a gateway component where security policies can be employed in a central location. A gateway can also perform functions that an agent cannot do, such as message routing, transformations, and failover. OWSM also has an extension for OSB, that allows us to use OWSM policies at the OSB (ESB) layer. These capabilities would suffice the requirements of most intranet SOA infrastructures.

Oracle positions the Oracle Enterprise Gateway as the first line of defence ("perimiter security") when SOA services are exposed to the outside world. This is the equivalent of a DMZ firewall. So it looks like Oracle Enteprise Gateway is a more expansive product that can do everything that OWSM does, plus all the bells and whistles.

Techniques for Service Identification in SOA

Its very important to use proper service identification techniques to identify services in an portfolio. In fact, service identification should be the first step in your service lifecycle management process.

Jotting down some of the techniques that we have been using for identifying services:

1. Domain decomposition approach - Look at the high level business entities and create entity services for them.
2. Top down BPM driven approach - Start from the business processes and divide them into sub-processes. Each business process consists of tasks & activities, that would orchestrate between different service components.
3. Business Goal driven approach -  Derive services from business goals. Decompose the business goals into a set of services that would help satisfy the business goal. Provide tracability between business goals and IT services by a Goal/Business Service matix.
4. Existing systems -  Service wrappers are created on existing systems - to surface them for orchestration in a business process or a composite service. This technique may not be appropriate if the existing IT landscape is not aligned with business goals.
5. UI driven approach - Identify/discover services based on the user interface requirements. UI technologies such as Flash, Silverlight, Ext-JS directly call JSON/REST services on back-end application servers.

Ruminating on SOA Governance

 SOA Governance has two dimensions. First – the processes and methodologies used. Second – the tools and products used for governance.

Quite often, people assume that the purchase of a SOA Governance tool would suffice for implementing SOA Governance. But the fact is that the tools would only help in automating certain enforcement policies and service lifecycle workflows. What is first needed is a framework of processes, policies and organization structure to be defined. Any governance process needs to embrace the trilogy of “people, process and technology”.

The following diagram illustrates this point and states the various activities that need to be done for implementing SOA Governance.

The Open Group has also published a SOA Governance Framework that can be accessed here.