L11 Service Design and REST

1. HÖNNUN OG SMÍÐI HUGBÚNAÐAR 2015
L11 SERVICE DESIGN AND REST

2. Agenda
How to Organise Systems
APIs and Service
Service Architecture
How to Model Services
REST

3. Reading
Microservices Grein eftir Martin Fowler og James Lewis
Martin Fowler - Microservices Youtube video, Martin Fowler
REST+JSON API Design - Best Practices for Developers Youtube
video, Les Hazlewood, CTO of Stormpath

4. How to Organise Systems

5. Conwey’s Law
Organisations which design systems ... are constrained to
produce designs which are copies of the communication
structures of these organizations
Team A Team B
Communication path:
Team B needs services
from team A
API, documentation,
and shared model

6. Conwey’s Law
Priorities of teams are not shared

7. Team Communications with other teams
Two ways:
Eliminate the communication path, possibly by
changing the team structure
Recognise that there is a communication path and
establish way for people to work successfully

8. Remember Conway
Responsibility of Teams
Teams must have complete
responsibility and
ownership of their services
Must have all the required
skill set to avoid
dependence on
Service architecture is very
much a human thing

9. APIs and Services

10. Trends in Architecture
Service Oriented Architecture dates back to mid 1990s
Web Services meaning XML and SOAP using an Enterprise Services
Bus
Confusions on terminology

11. Trends in Architecture
SOA as in Web Services using SOAP

12. 1. All teams will henceforth expose their data and functionality through
service interfaces
2. Teams must communicate with each other through these interfaces
3. There will be no other form of interprocess communication allowed
4. It doesn't matter what technology they use
5. All service interfaces, without exception, must be designed from the
ground up to be externalizable. No exceptions.
6. Anyone who doesn't do this will be fired.
Bezos’ Mandate (from Yegge’s Rant)

13. Service Oriented Architecture
SOA actually means that components of an application
act as interoperable services, and can be used
independently and recombined into other applications.
Engineering Software as a Service by David Patterson and Armando Fox

14. Microservices
In recent years a new term has emerged, Microservices:
The microservice architectural style is an approach to
developing a single application as a suite of small services, each
running in its own process and communicating with lightweight
mechanisms, often an HTTP resource API.
From the Lewis & Fowler article

15. Martin Fowler - Microservices
https://www.youtube.com/watch?v=2yko4TbC8cI
Martin Fowler
Microservices

17. Definition of SOA is useless because it is so overloaded
Microservice architecture is better but needs to be
clarified
Service Architecture

18. Each company should define what they mean by
Service Architecture
The Right Way
Service Architecture

19. A component is a software building block that is
independently replaceable
independently upgradable
Component

20. Service Architecture
Service Architecture means that components of an
application act as
interoperable services,
and can be used
independently and recombined into other applications

21. Service is a component that the replaceable and
independently upgradable
Definition of a Service
SERVICE
Implementation
Service API
Service
uses
other service

22. Services are like the Unix commands where output from
one is in input to another
SERVICE
Implementation
Service
API
SERVICE
ImplementationJson
Definition of a Service

23. Single Responsibility Principle
Gather together those things that change for the same
reason, and separate those things that change for
different reasons
Service boundaries focus on business boundaries

24. Separate Variations Principle
Identify the aspects of your application that vary and
separate them from what stays the same

25. Service vs. Monolith
Service is independently deployable
Monolith application
Single Deployment Unit
Service application
Multiple Deployment Unit

26. Scalability is provided with multiple machines - Y scaling
Possibility of better load management
Service vs. Monolith
Monoliths deployed on
multiple machines
X Scaling
Multiple Services deployed on
multiple machines
Y Scaling

27. Service Architecture

28. In Service Architecture we define services as a components that
communicate with a REST based HTTP remote call and AMQP
message
Componentization via Services
A service is a replaceable unit, it is independently replaceable and
upgradeable
A service has a published interface - an API
The only way to use the service is to use the API
Everything else in the service is encapsulated, including the data

29. REST
AMQP
Level 2 or 3 with JSon content
Message Protocol
Service API
This is how teams communicate

30. Feature teams provide
much better knowledge
in the domain
Team owns the entire
service from UI to DB
Organised Around Business Capabilities

31. In monolith
architecture it makes
sense to have front-
end developers as a
team and business
logic people as another
Monoliths can Organise Around Layers

32. Monoliths can Organise Around Layers
Due to Conway’s Law this
organisation leads to bad
systems, with lots of
duplication of effort

33. Monoliths can Organise Around Layers
The only thing that is
worse is to allow
developers of one team
to inherit classes that are
the responsibility of
another team
Formula for disaster!

34. Organised Around Business Capabilities
Communication paths
should as few as
possible - teams
should be fairly
independent
Any problematic
communication path
needs to be address

35. Software can be developed as projects, usually for others
Software can be developed as products for B2C or B2B markets
When building a product, a team is responsibility the whole
production of the product. Writing it, testing it, deploying it,
running it.
Companies need to figure out the right way
Products not Projects

36. The traditional SOA style applications favours using specific
routing system to facilitate service communication, for example an
Enterprise Service Bus (ESB)
Service Architecture favours the microservice approach: smart
endpoints and dumb pipes
This means that services use REST API to communicate and each
service is a dedicated business logic and output in form of JSon
Smart endpoints and dumb pipes

37. Smart endpoints and dumb pipes
System
A
System
B
System
C
Enterprise Service Bus
Routing
Logic
Routing
Logic
Routing
Logic
System
A
System
B
System
C
Routing
Logic
Routing
Logic
Routing
Logic
Network

38. Each service can be done in different programming language and
with different database
While such polyglot environments are more challenging to
manage, the possibility of using the best technology for the given
problem has true benefits
The goal is to make teams more responsible for the code they write
and test
Teams are responsible for coding, testing and deploying their own
services
Decentralised Governance

39. Data management is
part of service
Possibilities of
different
data stores
Possibilities of data
scaling
Decentralised Data Management

40. With multiple services, each deployable, the complexity of
managing the software deployment and monitoring becomes harder
The process of building, deploying and operating services needs
further developed to meet continuous delivery
One thing that must be looked into is to automate more tasks
Infrastructure Automation

41. Services will depend on other services
How to design if a dependant service is not available?
We must look into fall-back routines and other mechanisms to build
a robust systems
Use latency and fault tolerance support
Design for Failure

42. How to Model Services

43. Term microservices is sometimes used, but is misleading
Has nothing to do with lines of code
How big is a service?
Example definition:
Balance between integration points and size
Time: Can be rewritten in one iteration (2 weeks)
Features: All things that belong together

44. Loose Coupling
When services are loosely coupled, a change in one
service should not require a change in another
A loosely coupled service knows as little about the
services with which it collaborates
Source: Building Microservices

45. High Cohesion
We want related behaviour to sit together, and unrelated
to sit elsewhere
Group together stuff the belongs together, as in SRP
If you want to change something, it should change in one
place, as in DRY
Source: Building Microservices

46. Bounded Context
Concept that comes from Domain-driven Design (DDD)
Any given domain contains multiple bounded contexts,
and within each are “models” or “things” (or “objects”)
that do not need to be communicated outside
that are shared with other bounded contexts
The shared objects are define the explicit interface to the
bounded context
Source: Building Microservices

47. Bounded Context
Source: Martin Fowler, BoundedContext
http://martinfowler.com/bliki/BoundedContext.html

48. Bounded Context
Concept that comes from Domain-driven Design (DDD)
Any given domain contains multiple bounded contexts,
and within each are
objects that do not need to be
communicated outside
objects that are shared with other
bounded contexts
The shared objects are define the explicit interface to the
bounded context
Source: Building Microservices (figure is from the book)

49. REST

50. What is REST?
▪ An architectural style
– Representational State Transfer
▪ REST is defined in Roy Fielding’s dissertation from 2000

51. Adoption of REST

52. Why REST
▪ Scalability
▪ Generality
▪ Independence
▪ Latency
▪ Security
▪ Encapsulation

53. Les Hazlewood, CTO of Stormpath
REST+JSON API Design - Best Practices for Developers

55. HATEOAS
Hypermedia
As
The
Engine
Of
Application
State

56. What is REST?
▪ Quick and insufficient explanations:
– REST is nothing more than Web Service with the fancy URIs
– REST = CRUD – that is,
– POST, GET, PUT, DELETE = Create, Read, Update, Delete
– Almost but not quite

57. Better understanding
▪ REST stands for Representational State Transfer it is an
Architectural Style for distributed hypermedia systems
– It has nothing to do with XML, Json, HTTP or the Web
– Jason is one way to represent resources, but not the only
way

58. Better understanding
▪ HTTP/1.1 was built in a RESTful manner
– The Web is the largest known implementation of a system
conforming to the REST architectural style
▪ REST is not CRUD
– There are some similarities, but ‘similar’ is far from ‘same’
– In best case CRUD is a subset of REST

59. Better understanding
▪ Representational State Transfer
Client gets information about the data from the SERVER
CLIENT
SERVER
RESOURCE DATASESSION DATA
URI REQUEST
RESOURCE
HYPERMEDIA Stateless

60. Uniform Interface
▪ REST is defined by 4
interface constraints:
1. Identification of resources
2. Manipulation of resources
through representations
3. Self-descriptive messages
4. Hypermedia as the engine of
application state (HATEOAS)

61. Richardson Maturity Model (RMM)
▪ Level 0
– SOAP, XML RPC, POX
– Single URI
▪ Level 1
– URI Tunnelling
– Many URI, Single verb
▪ Level 2
– Many URIs, Many verbs
– CRUD services
▪ Level 3
– Level 2 + Hypermedia
– RESTful Services

62. Level 0
▪ Everything is packed in XML
– Ignoring all HTTP features
– SOAP envelope
– Ignores all status codes – 55 codes (including “418 I’m a
tepot”)

63. Level 1
▪ We understand that if every resource can be identified by a
URI, then we can POST to that URI for some expected result
– Many URI, one request method
– Still not good enough, as we skip some of the benefits of
the protocol
– POST cannot be cached

64. Level 2
▪ Different verbs or request methods (GET, PUT, and DELETE)
– and use them, as they were intended
Safe Idempotent
GET Yes Yes
PUT No Yes
DELETE No Yes
POST No No

65. Level 3
▪ HATEOAS – Hypermedia as the engine of Application State
– Don’t hardcode your values, use the navigational aspect of
the web
– Hardcoding is easy and fast, but hard to change – in a
distributed world, hard becomes ‘nearly impossible’
– With POJOs we don’t hardcode the memory address, we
use pointers

66. Level 3
▪ Why use the values of the second column if we can agree on
the keys for these value – the actions?
Action URI
Add new comment to a blog POST /blog/17/comment/
Get all the comments for blog entry number
17
GET /blog/17/comment/
Get user 167671 GET /user/167671
Update a user number 167671 PUT /user/167671

67. Level 3
▪ The response of “get user 167671” will contain keys like
“UPDATE” and the value is “http://example.is/user/167671”
Action URI
Add new comment to a blog POST /blog/17/comment/
Get all the comments for blog entry number
17
GET /blog/17/comment/
Get user 167671 GET /user/167671
Update a user number 167671 PUT /user/167671

68. Level 3
{
"id": "98423808305",
"from": {
"name": "Coca-Cola", "category": "Consumer_products”, "id": "40796308305"
},
"name": "A spectacular artwork made solely from used aluminum cans has been unvei
on top of the chalk cliffs of the Sussex coastline to mark the beginning of Recycle
Week.",
"picture": "http://photos-e.ak.fbcdn.net/hphotos-ak-snc1/
hs085.snc1/5041_98423808305_40796308305_1960517_6704612_s.jpg",
"source": "http://sphotos.ak.fbcdn.net/hphotos-ak-snc1/
hs085.snc1/5041_98423808305_40796308305_1960517_6704612_n.jpg",
"link": "http://www.facebook.com/photo.php?pid=1960517&id=40796308305",
"comments": {
"data": [
{
"id": "98423808305_1152797",
"from": {
"name": "Caitlin Catherine Kennedy",
"id": "1658825260"
},
"paging": {
"next": "https://graph.facebook.com/98423808305/comments?limit=25&offset=25"
} }}
HATEOAS

69. Resources
▪ Nouns, not verbs
– Examples: Account, Group, Customer
– Not behaviour
▪ Two types
– Collection of resources
– Instance of a resource
/applications
/applications/7828

70. REST Behaviour
▪ GET to get resource
▪ POST to add resource
▪ PUT to update resource
▪ DELETE to delete resource
▪ HEAD to get header information

71. GET
someservice.com/api/customer/3829
POST
someservice.com/api/customer/
REST examples
PUT
someservice.com/api/customer/3829
Getting
Adding
Updating

72. GET
▪ On the parent resource: collection
GET /users
200 OK
{
“users”: [
{
“username”: “olandri”,
...
},
{
“username”: …
}

73. ▪ On the parent resource, give me a specific instance
GET /users/789
200 OK
{
{ “username”: “olandri”,
...
}
}
GET

74. POST as Create
▪ On the parent resource
POST /users
{
“username”: “olandri”,
“firstname”: “Ólafur Andri”,
“lastname”: “Ragnarsson”
}
201 Created
Location: https://api.rufan.com/users/789

75. PUT as Update
▪ On the parent resource
– Allows partial updates, which is important for complex data
type
PUT /users/789
{
“username”: “olandri”,
}
200 OK

76. Endpoint considerations
▪ For internal use, you can use anything
– http://www.foo.com/dev/api/
▪ But if you want others to use
– http://api.rufan.com/v1.0/

77. Versions
▪ Two ways
▪ URL
– https://api.rufan.com/v1
▪ Media-Type
– Application/json;application&v=1

78. JSON
▪ JS in JSON is JavaScript
▪ XML is also possible
▪ JSON is fits well with JavaScript manipulation
▪ Libraries make all this easier
▪ Maps well to objects like POJOs
▪ Compact format, much better space complexity than XML

79. Example
{
"firstName": "John",
"lastName": "Smith",
"isAlive": true,
"age": 25,
"height_cm": 167.6,
"address": {
"streetAddress": "21 2nd Street",
"city": "New York",
"state": "NY",
"postalCode": "10021-3100"
},
"phoneNumbers": [
{
"type": "home",
"number": "212 555-1234"
},
{
"type": "office",
"number": "646 555-4567"
}
],
"children": [],
"spouse": null
}

80. Some design rules:
Determine the resources first
Transparant as opposed to opaque
Lowercase
As Java package, domain specific with general terms closer to the root
Design by intention of results
Resource names are plural, customers not customer
If /a/b is valid, so is /a
Endpoint Design
/customers/{id}
/customers/117 Returns customer with id=117
Use { } for parameters

81. ▪ Example: School, Student, and Classes in their normal
relationship
– schools have zero or more students
– schools have zero or more classes
– students have zero or more classes
– classes have zero or more students
Resource Oriented Design

82. Resource Oriented Design
http://example.com/lms/schools => list of schools
http://example.com/lms/schools/{school} => info about one school
http://example.com/lms/schools/{school}/students => list of students
http://example.com/lms/schools/{school}/students/{student}
=> info on one student
http://example.com/lms/schools/{school}/students/{student}/courses
=> list of courses (as links, not full resources) student is enrolled in
http://example.com/lms/schools/{school}/courses => list of courses
http://example.com/lms/schools/{school}/courses/{course}
=> info on one course
http://example.com/lms/schools/{school}/courses/{course}/students
=> list of students (as links, not full resources) enrolled in course

83. http://www.example.com/lms/students/123
{
"ID" : 123,
"name": "Name of Student",
"SSN" : 123456789,
"DateOfBirth" : "2001-01-01"
}
Resource Oriented Design

84. http://www.example.com√lms/students/123
{
"Classes" : [
{
"name" : ”History",
"link" : " http://www.example.com/classes/117"
},
{
"name" : ”New Technology",
"link" : " http://www.example.com/classes/118"
}
]
}
Resource Oriented Design

85. Architecture
Client
Domain
Data
Source
CMS
REST
Web
Server DB

86. JavaScript
calls
REST
API
to
get
Json
array

87. What REST is not
▪ Silver bullet
▪ Not easy although simple
▪ Isn’t tied to the web
▪ Not perfect
– Client holds application state
– Latency
– Integrity

88. Summary
▪ REST is HTTP done right
▪ Architecture style
▪ Not so easy to get right
▪ Trend is towards APIs