Web API course 2015

1. « BUILD, DOCUMENT, MANAGE » CLASS
RESTful Web APIs
February 2015
@SteveSfartz

2. APIS ARE THE FUEL OF THE WEB
APIGee 2015 – Web API Strategy

3. A BIT OF THEORY
REST, web APIs, RESTful web APIs

4. THE REST STYLE
Based on the web’s architecture
Formalised by Roy T. Fielding in his PhD dissertation
The main properties of REST
- Client-server
- Stateless
- Every request contains the information
required to process it
- REST is cache-friendly
- Interoperable
- Uniform interface
- Loose coupling
Constraints of a REST interface
- identifiable resources
- resources are manipulated via
their representations
- messages are self-contained
- hypermedia as the engine of
application state (HATEOAS)

5. RICHARSON MATURITY MODEL
martinfowler.com/articles/richardsonMaturityModel.html

6. Client Service
AppointmentService
GetOpenTimeSlot
MakeAppointment
TimeSlotsList
ReservationResult
LEVEL0
POX, SINGLE URI, TRANSPORT
• The systems focus are service end point URI and one
HTTP verb (likely POST verb) for communication.

7. Client
Doctors
http://klinik.com/
doctors/eberwein
slots/15092012
TimeSlotsList
ReservationResult
Slots
POST
POST
LEVEL1
RESOURCES
• Introduces resources, URIs, but 1 HTTP verb.
• Handling complexity by using divide and conquer,
breaking a large endpoint down into multiple
resources.

8. Client
Doctors
http://klinik.com/
doctors/eberwein
?date=…&open=1
slots/15092012
200 OK TimeSlotsList
204 CREATED ReservationResult
Slots
GET
POST
LEVEL2
HTTP VERBS
• The system relies on more HTTP verbs and
HTTP response codes on each resource.

9. Client
Doctors
http://klinik.com/
doctors/eberwein
?date=…&open=1
slots/15092012
200 OK TimeSlotsList
<link rel = "/linkrels/slot/book"
uri = "/slots/15092012"/>
204 CREATED ReservationResult
Slots
GET
POST
LEVEL3
HYPERMEDIA
• Introduces discoverability, providing a way of making
a protocol more self-documenting.

10. FROM REST TO WEB APIS
http://blog.restlet.com/2013/05/02/how-much-rest-should-your-web-api-get/

11. WEB APIS LIFE CYCLE
design
build
host
manage
document
promote
… and version

12. CLASS HOLS
frameworks
Restlet Framework
Sails.js
management
Runscope
APISpark
web API platform
APISpark
tooling
POSTMAN
Swagger Editor
Restlet Studio
Intellij IDEA
design
build
host
manage
document
promote

13. BUILD
Do It Yourself with SAIL.JS

14. FIRST WEB API WITH SAILS.JS BLUEPRINT
• POSTMAN collection : http://goo.gl/2MSQZY
> sails new firstapi-withsailsjs
> sails generate api users
> sails lift

15. QUESTIONS / ANSWERS
• Terminology : /users for a collection
• Path : support both user and users/
• PUT versus POST : design option
• HTTP statuts : http://restapitutorial.com/

16. BUILD
with the APISpark PaaS

17. APISPARK
the first self-service platform for APIs
http://restlet.com/products/apispark/features/

18. ALL-IN-ONE WEB PLATFORM
Create your Web API quickly
– 5 minutes scenario based on existing API template (e.g. blog API)
– Open source foundation (Restlet Framework) , the full code can be
exported
Integrated hosting
– Scalable and reactive backend (low latency, integrated management)
– Permanent availability 24/24 7/7 and secured (SSL confidentiality,
precise management of authorizations)
Automatic versioning
– Manage several versions of your APIs
– Free to update your APIs with no impact on current users
– Simple and clear lifecycle (draft, published, deprecated, archived,
removed)

19. Automatic documentation
– Always up-to-date
– Test your API live
– Easy export to multiple formats
Clients SDKs generation
– Ease the use of your API
– Support of most popular platforms (iPhone/iPad, Android,
Java, .NET, PHP, Python)
Community management
– Manage the users and their signins
– Private or public communities
– Send announcements
ALL-IN-ONE WEB PLATFORM

20. COMPOSING APISPARK CELLS
Entity Store File Store
Custom API
Java iOS JS
HTTP HTTP

21. HOL 1
• sign in APISpark
• take the tutorial « Turn a Gsheet into a web API”
– http://restlet.com/technical-
resources/apispark/tutorials/
• gsheet sample
– list rows
– add a row
• invoke with
POSTMAN

22. HOL 2
• sign in on APISpark
• take the tutorial “Create a web API”
– http://restlet.com/technical-
resources/apispark/tutorials/
• invoke with POSTMAN
• to go further : host an angular app
– check sample :
https://github.com/guiblondeau/bookStore

23. MONITOR
with Runscope

24. WHY ?
• Remember: web APIs are your company key assets
• Technical monitoring
– ensure they are always up
– give visibility to your consumers
– detect issues (low perfs)
– ease maintenance (compatibility test suites)
• Business monitor
– Analytics, Analytics, Analytics !!!

25. HOL 3
• Monitoring with RunScope
– import your POSTMAN collection
• Traffic Inspector > Import Requests
– create test
– run
– add assertions
– schedule

26. DOCUMENT YOUR WEB API
Swagger, RAML, APIBlueprint

27. HOW ?
• Top down : create manually or via an editor
• Bottom up : code annotations, introspection
• No standardization
– Swagger
– RAML
– API-blueprint
– …

28. HOL 4
• Document via the Swagger Editor
– turn public your APISpark documentation
• Web API > General Information > Public access (true)
– load your swagger2 endpoint in editor.swagger.io/
– adapt definition
– invoke

29. COMPARISON
SmartBear 2014

30. SYNTHESIS
• No clear winner at this stage
– don’t get locked-in
– translate your API definition between various languages
– use the best of each language ecosystem (tooling,
directory)
• Take API copyright seriously (now)
– play nice in the API economy
– choose a license for your Web API
– publish it to the « API Commons »
– verify the legal terms of the APIs you depend on

31. BOTTOM UP APPROACH
Document via Annotations or Introspection

32. BOTTOM UP WITH RESTLET INTROSPECTOR
JAX-RS API
Restlet API
Spring REST
Swagger
annotations
Bean Validation
annotations
Google Cloud
Endpoints API
1. Select
a main
Java API
Java
source
code
3. Write your
Java code
JAXB
annotations
2. Add extra
annotation
APIs
Jackson
annotations
RESTful
Web API
4. Get your
web API

33. DOCUMENT YOUR WEB API
IN JAVA LANGUAGE
RESTful
Web API
Web API
definition
1. Code your
web API
(iterate)
2. Introspect
source code
3. Complete
API definition
manually
Intro-
spector
4. Select
target API
specs
RAML
API
Blueprint
Swagger
Google API
Discovery
WADL

34. HOL 5
• clone https://github.com/restlet/restlet-sample-
descriptor.git
• introspect
• open Descriptor
on APISpark
• play with
annotations
• introspect again
• turn access to public
• open Swagger2
endpoint in Studio

35. HOL 6
• Generate source code from an existing APISpark API
– API > generate downloads
– download tab > get source code
• Unzip, maven build
• Add Swagger support

36. MANAGE YOUR WEB API

37. HOW IT WORKS
• Reverse proxy in front of your API
– Filter incoming calls
– Authentication, Authorizations
– Firewall
– Analytics
– …

38. HOL 7
• Leverage the APISpark firewall
– add a RateLimiter to an APISpark Full Stack API
• Settings > Rate Limits (3 calls / minute / user)
– Redeploy your Web API
– Invoke >3 times and check for HTTP status 429

39. APISPARK CONNECTOR
• APISpark Connector
– User friendly interface to configure your proxy
• Open-source proxy
– Part of the Restlet Framework APISpark extension
• Deployment
– as a standalone agent
– or embedded in a Restlet application

40. HOL 8
• Add a RateLimiter to a local Web API
– see http://restlet.com/technical-
resources/apispark/guide/manage/connectors
– create a Connector on APISpark
– configure (add a Rate limiter)
– deploy the connector
– install the agent on your local devenv

41. BUILD / FINE-GRAINED CONTROL
with the Restlet Framework

42. WEB API FRAMEWORK FOR JAVA
OPEN SOURCE SINCE 2005
6 editions
44 extensions
1,5 M downloads
100 000 developers
Version 2.3.0 launched
in November 2014
Covers our ROA/D
API guidelines
Consistent client & server API
Powerful routing & filtering
Comprehensive web security
Aligned with REST & HTTP
Fast & scalable

43. HOL 9
• load the web API reference implementation
– https://github.com/restlet/restlet-tutorial
• run org.restlet.tutorial.WebApiTutorial
• invoke via POSTMAN

44. API DESIGNS
a bit of architecture

45. WEB API ARCHITECTURE
• basic design
– no distinction between app and backend
– the app is the sum of data and UX
app data

46. WEB API ARCHITECTURE
• « api-aware » design
– multiple apps, multiple devices, need to evolve
independently
app dataapiapp

47. WEB API ARCHITECTURE
• « api-centric » design
– your API gets richer to simplify app code
– business logic moves to the API, as well as security, and
versioning stakes
app dataapiapp

48. WEB API ARCHITECTURE
• « channel oriented » design
– taking into accounts specifis (sync/async, bandwith,
streaming, callbacks, IoT)
– automated generation of client SDKs adapted to
consumption scenarios
app dataapichannelapp channel

49. RESTFULL WEB APIS RESSOURCES
• ongoing debate regarding the proper way to design
– Hypermedia APIs (see this O’Reilly book)
– REST endpoints (see Roy T. Fielding’s tweet)
– REST APIs (see this O’Reilly book and Roy T. Fielding’s
blog post)
– RESTful Web Services (see this O’Reilly book)
– RESTful Web APIs (see Restlet in Action’ book)
– Pragmatic REST (see Kin Lane /API Evangelist web page)

50. SEE YOU IN THE WEB API GALAXY
mailto : steve@sfartz.com
twitter : @SteveSfartz
blog : Think big … mais pas trop !
« Vision without execution is
hallucination ». Thomas Edison
« Tout objectif flou se traduit par des
conneries précises » Frédéric Dard