1. Marlon Dumas marlon . dumas ät ut . ee
MTAT Enterprise System Integration Lecture 6: Service Analysis and REST API Design
Marlon Dumas
marlon . dumas ät ut . ee

2. Service Analysis & Design
Service Analysis. identification and definition of the business services that an organization provides or consumes, internally or externally.
 Collection of business-level services, their context and their interactions
Service API Design. identification and definition of technical services (e.g. REST) to support the delivery of business services.
 Collection of service APIs (operations, inputs & outputs)

3. Decomposing Information Systems
Functional or capability-driven decomposition
Which business functions, capabilities or specialization perform work in the organization (organizational chart)
Process-driven decomposition
Which chains of activities create value to the organization?
Data-driven decomposition
What information is stored & circulates in the organization?

4. Service Analysis and Design Methods
Capability-driven methods
Steve Jones: Enterprise SOA Adoption Strategies. InfoQ, 2005.
Process-driven methods
Thomas Erl: “Service-Oriented Architecture, Concepts, Technology, and Design”, Prentice Hall, 2005
Data-driven methods
Petri Selonen: From Requirements to a RESTful Web Service. In REST: From Research to Practice, Springer, 2011

5. Capability-driven Service Analysis
Sub-system where a collection of tasks are performed to achieve a goal.
Actor
User or “external” system (application) that interacts with a given service
Interaction
An encounter between two services or between an actor and a service to achieve a goal.
Includes: physical or electronic, manual or automatic

6. Capability-driven Service Analysis
WHAT
WHO
WHY
HOW
definition of the services scope: what the services are
Services
external actors driving or interacting with the services
Actors
reasons of the service-to-service and service-to-actor interactions
Interactions
API Design (resources & operations)
details of services to be delivered by the IT team

7. Capability-driven Analysis – Levels
The framework is applied at increasingly finer levels of granularity
Level 0. Definition of the core services to the business domain. Level 1. Decomposition of the Level 0 model into finer-grained services for each core service.
Level 2+ Refinements of previous levels to identify support & shared services integrating & complementing the services already defined.

8. Pharmak example – sub-systems
Sales
contacts customer
receives order from customer
checks stock
requests order to be shipped - if item(s) available
Manufacture
makes item(s)
Requests order to be shipped - after manufacturing item(s)
Logistics & Warehouse
adds new item(s) into stock
requests an external company, or internal logistics, to deliver an order to a customer
receives supplies from suppliers
Finance
orders raw materials from suppliers
receives invoice from suppliers
prepares invoice for customer

9. Pharmak example – actors
Customer
organization which buys, and potentially distributes manufactured products
Supplier
manufacturer or wholesaler of components/raw materials
Logistics Provider:
provides storage and transport services

10. “Level 0” Context Diagram
What
Who
Why
Rule of thumb:
2-8 services at this level

11. “Level 1” Context Diagram (Manufacture)
What
Who
Why

12. Process-Driven Service Design
Identify which process(es) need to be supported and their actors
Capture each process (e.g. as a process model)
Analyze tasks/events in process model to identify:
Atomic interactions (operations) that the process should provide
Atomic interactions (operations) that the process requires from other systems

13. Process-Driven Service Design Steps 1. Identifying Process & Actors
Supplier
Service Required by Process
Process we need to support
External Actor
Service Required by Process
From a design-time perspective, an SOA is built around interfaces and process models.

14. Process-Driven Service Design 2. Capturing the Order Management Process

15. Step 3. Identify operations (Order Management Service)
Provided operations (to customer)
Receive RQF
Receive order
Required operations
From inventory control
Check stock availability
Request order shipment
Invoicing
Request invoicing
From

16. Step 3. Identify Operations
Order Management
RFQ
Place order
Inventory Management
Check stock availability
Request shipment
Invoicing
Request invoicing
Customer
Receive RFQ response
Receive invoice
Receive shipment notification

17. Step 3. Identify Operations
Less obvious provided operations of order management service
Cancel order/request order cancellation
Modify order/request order modification
Check order status …

18. Step 3. Identify operations
Less obvious required operations
To prepare quote
Retrieve price list
Retrieve customer data (contractual terms)
To prepare shipment order
Retrieve customer delivery data
To prepare invoice request
Retrieve customer invoicing data

19. Step 3. Identify Operations
Order Management
RFQ
Place order
Request order cancel.
Check order status …
Inventory Management
Check stock availability
Request shipment
Invoicing
Request invoicing
Customer
Receive RFQ response
Receive invoice
Receive shipment notification
Catalogue (Price List)
Retrieve price
CRM
Retrieve contract terms?
Retrieve invoicing address
Retrieve shipment address ..

20. Process-Driven Design Drawbacks and Limitations
Some services remain coarse-grained
Cf. for example order management service or CRM service – lots of operations, can we break down?
How complete is the design?
Did we forget something in the order management service? How do we check completeness?
Evolution
Processes change frequently, so service design has to follow up

21. Data-Driven Service Design
Suitable particularly for RESTful service design
Starts from a data model
Key entities in model become “resources”
CRUD framework used to identify operations
One possible method (you must read it!):
Petri Selonen: From Requirements to a RESTful Web Service. In REST: From Research to Practice, Springer, 2011

22. Data-Driven Service Design
Capture domain model
High-level data model
Refine domain model into resource model
Identify resources of different types and hypermedia relations
Derive REST API
Use CRUD (or SCRUD) framework

23. Example: Domain Model
© P. Selonen, 2011

24. Deriving Resource Model: Principles
“Main entity” (or entities) becomes a <<root>> resource
By default classes map to a an <<item>> resource with a URI and a representation.
Attributes of classes map to attributes of respective <<item>> resources and form part of the resource representation. Identifiers are designated with <<id>>
By default, associations become <<ref>> associations between resources that appear as links in the representations. Bidirectional associations are represented as two directed <<ref>> associations.
© P. Selonen, 2011

25. Deriving Resource Model: Principles
Associations representing collections become <<container>> resources containing <<item>> resources.
Composite associations become <<sub>> associations between a <<container>> and an <<item>>
Queries (e.g. filters) become <<projection>> over container resources
Constraints may be added in the resource model, e.g. <<readOnly>>,, <<appendOnly>>
© P. Selonen, 2011

26. Example: Resource Model (top-level)
© P. Selonen, 2011

27. Example: Resource Model (zoomed)
© P. Selonen, 2011

28. Eliciting Operations: SCRUD Framework
What operation(s) allow us to:
Search instances in a container
Create an item
Read the data of an item
Update an item or container
Delete an item
Output of capability-driven analysis or process-driven analysis helps us to determine which operations are business-relevant

29. Example: REST API
© P. Selonen, 2011

30. Container Projections
© P. Selonen, 2011

31. Example REST API (projections)
© P. Selonen, 2011

32. Beyond Resource Models: Resource State Diagrams
Resource models focus on data
When a resource has a non-trivial lifecycle (e.g. a PO), it may be useful to model its behavior as a state diagram where transitions correspond to operations (URI + HTTP verb)

33. Example: State Diagram of PO

34. API of POs Method URI template Relation Current state New state
Comments
POST
/pos
createPO
Pending confirmation
Submit partial representation
/pos/{po.id}/accept
acceptPO
Open
Use empty body
DELETE
rejectPO
Rejected
PUT
/pos/{po.id}
updatePO
Submit new full representation
closePO
Closed
/pos/{po.id}/updates
requestPOUpdate
Pending update
Submit new end date
/pos/{po.id}/updates/{up.id}/accept
acceptPOUpdate
rejectPOUpdate

35. PO Resource State Diagram

36. Summary
Service analysis & design methods allow us to go from business models to REST service APIs
We have seen three methods:
capability-driven method (high-level  context diagrams)
process-driven method (intermediate level  coarse-grained service API)
data-driven method (technical level  REST API)