1. Enlighten your software
REST API design & dev
Domingo Suárez Torres
@domix
http://github.com/domix
http://domingosuarez.com
Una propuesta de: “Como construir APIs REST
para sistemas distribuidos con alta
escalabilidad y resilencia"
1/jul/2015

2. Agenda
• Preamble
• Disclaimer
• Context
• Motivation
• API
• Contract
• Programming model
(architecture style)

3. Preamble

4. Disclaimer
• This talk and its contents are based in my own
experience.
• I’m not trying to say all the following IS the way to
do the right thing. Just my opinion. :)
• All I want is to share my experience with the
community.
• This talk is huge. Hope I can finish on time.

5. Context
• I’m not covering Hypermedia REST APIs
• I’m a JVM guy, so you will see lots of JVM
references. Sorry.

6. Motivation
• Functional requirements is THE challenge.
• API Documentation is always a PITA, keep sync
with the maintenance, new features, fixes, etc.
• Build any API (REST, SOAP, RPC) is hard.
• Development tools choice (programming
language, libraries, frameworks, runtime, etc).
• Non functional requirements, quality attributes.

7. SOAP
No longer an acronym. Since 1.2

8. SOAP
• Characteristics
• Extensibility (security, routing)
• Neutrality (transport protocol)
• Independence (programming model)

9. SOAP architecture
• Several layers of specifications for:
• Message format
• Message Exchange Patterns
• Underlying transport protocol bindings
• Message processing models
• Protocol extensibility

10. SOAP
• Web Services Description Language (WSDL)
• Universal Description Discovery and Integration
(UDDI)

11. SOAP
• Complex specification for vendors
• Developers take time to grok
• Sometimes very long time
• Misunderstanding of the guidelines.

12. I like SOAP intentions

13. I dislike SOAP complexity

14. API Contract

15. API Contract
• Always is over there. Implicit/Explicit
• You should have one.
• You should know it.
• No matter if you build it or you consume the API.
• You should give it so much love.
• Learn to love it.

16. API contract approaches
• Contract last
• Code driven contract
• Contract first
• Upfront design

17. Contract last
• Sadly is the commonest.
• Server-side developers dictate the contract.
• Most of the time with only one perspective.
• Implementator perspective VS consumer perpective
• Flaky. If missing test cases. Fragile.
• The documentation is done at the end.
• Bottleneck.

18. Contract first
• Upfront design API
• Consumer perspective design
• Reusability
• Versioning
• Performance

19. The contract as corner stone for REST APIs

20. How to build the contract?

21. Tools

25. So many others :)

26. RAML, my favorite
• YAML dialect + JSON schema #ftw (types)
• Readable for humans.
• Can be procesable by machines.
• Design clear, correct, precise & consistent APIs.
• No vendor lock-in.

31. Design & build

36. raml + raml-mockup
We can deliver an API in days or hours

37. RAML & code generation
• Server side
• JAX-RS
• Client
• Square Retrofit
• Documentation
• HTML

38. raml2code
• OpenSource project from Grupo Expansión
• Generates Plain Old Java/Groovy Objects
• Generates JAX-RS interfases
• Generates an API client with Retrofit
• Can run in Android also in any JVM application.

41. Nice, now I know how to
create a contract. What’s next?

42. Programming model
Architecture

43. SOA + EDA

44. Services
• Build, deploy, and monitor any kind of services in
agile, efficient way with open standards.
• Deployment on-premise, in the cloud, mix of both.
• Deploy services independently from each other.
• Decoupled & scale linearly across commodity
hardware.

45. Wait, a buzzword
is coming…

46. MicroServices architecture
• Service Contracts
• RAML
• Exposing new & existing services
• Enterprise Integration Patterns (integration, routing,
transformation)
• Discovery of services
• Service Registry

47. MicroServices architecture
• Coordination across services
• Event Bus, (smart service, dump pipe)
• Managing complex deployments and their scalability
• Build Tool, CI, DevOps (Chef, Puppet), Linux
Containers, Cloud, monitoring
• Visibility and correlation across services
• Event correlation, ElasticSearch, Logstash, Kibana.

48. Sounds nice, but…

50. Implementation details

51. Spring Boot is awesome

52. –Spring Boot reference documentation
“Spring Boot makes it easy to create stand-
alone, production-grade Spring based
Applications that you can “just run”. We take an
opinionated view of the Spring platform and
third-party libraries so you can get started with
minimum fuss. Most Spring Boot applications
need very little Spring configuration.”

53. Spring Boot
• Embedded Servlet container
• Tomcat
• Jetty
• Undertow
• Executable jar file. Key feature for microservices!
• Monitoring capabilities thanks to actuator
• HealthChecks
• Metrics (Dropwizard aka Coda Hale Metrics)
• Jolokia

54. Spring Boot & JAX-RS
• Jersey 2.x support out of the box
• Just use the Jersey Starter
• spring-boot-starter-jersey
• raml2code generates JAX-RS artifacts, remember?

55. Spring Cloud
• Distributed/versioned configuration
• Service registration and discovery
• Routing
• Service-to-service calls
• Load balancing
• Circuit Breakers
• Global locks
• Leadership election and cluster state
• Distributed messaging

56. Netflix OSS
• Netflix is released tons of good stuff.
• Reactive Extensions for Java
• Hystrix (Circuit breaker)
• Eureka (Service registry)
• Archaius (Configuration management)
• Zuul (Dynamic routing, monitoring, resilience, security)
• And many more…

57. Spring Boot loves
Netflix OSS

58. Spring Boot & Spring Cloud
for impatient developers

60. Demo

61. Each circle is a Docker container
read/write
Hystrix send metrics
Turbine listen events
Turbine generates
a http stream

62. Acknowledgments
• To all the platform team at Grupo Expansión
• Alvaro Cabrera (@pateketrueke)
• Anallely Olivares (@tsunllly)
• Angel Pimentel (@blzb)
• Eduardo Diaz (@iamedu)
• Tomás Salazar (@atomsfat)

63. Enlighten your software
¿Preguntas?
@domix
domingo.suarez@gmail.com
http://github.com/domix
http://domingosuarez.com