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

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)

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?

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

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

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

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.

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

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

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

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

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

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.

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

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

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

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 …

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

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 ..

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

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

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

Example: Domain Model © P. Selonen, 2011

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

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

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

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

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

Example: REST API © P. Selonen, 2011

Container Projections © P. Selonen, 2011

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

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)

Example: State Diagram of PO

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

PO Resource State Diagram

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)