The best way to document service interfaces (SOA)

[David McCracken]

Hi there,

I'm new to EA and learning my way around the product.  I'd like to use it to model and document service interfaces for a SOA based solution.  We split up Integration Documentation into three groups:

1. Service provider specifications (what data payload a system provides).
2. Interface specifications (any content enrichment or other logic performed by the Integration Layer)
3. Service consumer specifications (mainly for usage volumetrics / capacity planning for the providers)

What would be the best way to model and document this information?

The type of information we want to capture is

1. Service provider specifications:

Overview            
      Scope      
      Usage      
      Context      
Interface Specification            
      Overview      
      For Each Interface      
                Identity
            Overview
            Popular use cases / Usage Guide
            Target Interfaces
            Data Structure
            Sample Messages
            Data Transformation
            Validation
            Variability Provided
            Schemas
            WSDLs
      Security Design      Authentication
            Authorisation
            Data Confidentiality
      Exception Handling      
      Monitoring      
      Logging and Notifications      


2. Interface specifications

Overview            
      Scope      
      Usage      
      Context      
Interface Specification            
      Overview      
      For Each Interface      
                Identity
            Overview
            Popular use cases / Usage Guide
            Target Consumers
            Data Structure
            Sample Messages
            Variability Provided
            XML Schemas
            WSDLs
      Security Design      Authentication
            Authorisation
            Data Confidentiality
      Possible exceptions      
      Monitoring      
      Logging and Notifications      


3. Service consumer specifications
      
Overview            
      Scope      
      Usage      
      Context      
Interface Specification            
      Overview      
      For Each Interface      
                Overview
            Interface Specification
            Popular use cases
            Usage Volumetrics
            Availability
            Data Transformation
      Security Design      Authentication
            Authorisation
            Data Confidentiality
      Exception Handling      
      Monitoring      
      Logging and Notifications      


The main goals we are trying to achieve are:

1. To understand the dependencies between services (i.e. if a provider interface changes or will be delivered late, which consumers are impacted) as well as
2. Discoverablility / searchable for reuse.


I'd like to model this information in EA (possibly several models) with a view to then auto generating documentation from these models to service as Word or PDF specs.


Can someone please suggest the best way this can be done in EA?


Regards,

David.

[Geert Bellekens]

...
Can someone please suggest the best way this can be done in EA?

Hire a specialised consultant?
Check Value Added Resellers  for a consultant in your area.

It can definitely be done in EA, but I think your question is a bit too broad to be solved through the user forum.

Geert

[David McCracken]

At this stage my company is still evaluating EA.

I have found this guide - http://www.sparxsystems.com.au/downloads/ebooks/Modeling%20Service-Oriented%20Architectures.pdf

It describes the approach I had in mind, documenting the end to end flows with BPMN and then using WSDL and XSD to describe the interface contracts.

I am also looking at SoaML and SOMF to see if they can help.  

[David McCracken]

Just to help others with the same problem, I will attempt at using SoaML to meet my needs.

I will attempt to create an individual model for every provider(s) - service - consumer(s) relationship (i.e. participant - service contract), and then reference them all together in a single Services Architecture (UML Collaboration) digram.

I will also go with a UML Activity diagram (or BPMN) to document the business processes.  

I will then attempt to link the two in EA so you can click on a participant and switch between the service views.

It's slow progress so far, I can draw exactly the model I'm after on a whiteboard quite easily but have problems doing this within EA.

E.g. I want a 'Participant'.  In the EA Toolbox there are four options here:

1. SOA Contracts > Participant Architecture > Class
2. SOA Contracts > Participant Architecture > Component
3. SOA Services > Participant > Class
4. SOA Services > Participant > Component

Which one should I use?

I want to make one of these diagrams -> http://www.sparxsystems.com/enterprise_architect_user_guide/9.2/images/examplesoamldiagram.png