The document presents an overview of the Restlet platform and its capabilities for managing Java-based web APIs through Apispark, a full-stack PaaS. It details the features of the platform, including automatic versioning, documentation, and community management, along with hands-on lab instructions for creating custom web APIs. The document also covers various Java API coding standards and best practices, emphasizing the ease of integrating and documenting web APIs.

1. DOCUMENT AND MANAGE
YOUR JAVA-BASED WEB API WITH APISPARK
Full stack PaaS for web APIs
http://apispark.com
May 27, 2014
Web API framework for Java
http://restlet.com

2. PRESENTER
ENTREPRENEUR AND WEB API EXPERT
Jérôme LOUVEL
 CEO of Restlet
 12 years of experience in software (EU and US)
 Restlet Framework creator (2005)
 JAX-RS 1.0 expert in JCP (JSR-311)
 Contributor to “RESTful Web Services” (O’Reilly)
 Co-author of “Restlet in Action” (Manning)
Contact
 jlouvel@restlet.com
 Twitter : @jlouvel
 Blog : blog.restlet.com

3. AGENDA
 1) Overview of Restlet Platform (10’)
 2) Documenting and managing your Java-based
web API (20’)
 3) Hands-on lab (20’)
– Sign in to APISpark
– Craft a custom web API
– Generate « API Commons » manifest
– Display Swagger UI for your web API

4. 1) OVERVIEW OF RESTLET PLATFORM

5. WEB API PROJECT
TYPICAL LIFE CYCLE
Create Host Manage Use Promote
1) Do It Yourself (DIY)
2) Platform as a Service (PaaS)

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

7. RESTLET FRAMEWORK
SIX CONSISTENT EDITIONS, CLIENT & SERVER JAVA API

8. APISPARK
FULL STACK PAAS FOR WEB APIS
Send us your feed-back
and help us making it the
best PaaS for Web APIs !

9. FEATURES 1/2
All-in-one platform for Web APIs
 Create your Web API quickly
– 5 minutes scenario based on existing API template (e.g. blog API)
– Few hours scenario from scratch or by customizing an existing API template
(from the APIs catalog)
– Open source foundation (Restlet Framework) , the full code can be exported
 Integrated hosting
– Scalable and reactive backend (low latency, integrated management)
– Permanent availability 24/24h et 7/7d (no maintenance window) and
secured (SSL confidentiality, precise management of authorizations)
 Automatic versioning
– Manage several versions of your APIs at the same time at the same cost
– Free to update your APIs with no impact on current users
– Simple and clear lifecycle (draft, published, deprecated, archived, removed)

10. All-in-one platform for Web APIs
 Automatic documentation
– Always up-to-date
– Test your API live on the Net
– Easy export in PDF and HTML
 Clients kits 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 publics announcements or private messages
– Integration with social networks
FEATURES 2/2

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

12. STRUCTURE OF WEB APIS
API Contract
Implementation
Runtime
Web API
template
Complete
web API
HTTP HTTPS

13. 2) DOCUMENTING & MANAGING
Your Java-based web API

14. CODE YOUR WEB API
IN JAVA LANGUAGE
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

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

16. DON’T GET LOCKED-IN
API DEFINITION PORTABILITY & COPYRIGHT
– No clear winner at this stage
 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: open your API definition
– select a Creative Commons or Open Source license
– publish to the « API Commons »
 verify the legal terms of the APIs you depend on

17. DEMONSTRATION

18. YOUR DASHBOARD

19. LAUNCH INTROSPECTOR TOOL
SUPPORTS RESTLET API, NEW JAVA APIS COMING
1) Launch from
your IDE or the
command line
2) Web API
definition pushed
to APISpark

20. DISPLAY YOUR WEB API DOC
RELAUNCH INTROSPECTOR TO KEEP IN SYNC

21. CHECK OUT API COMMONS TAB
WEB API MANIFEST BASED ON SWAGGER

23. CHECK OUT THE HOSTED SWAGGER UI
EMBEDDED IN YOUR WEB SITE

24. WHAT WE ARE WORKING ON!
 Restlet Framework (open source)
– introspect all main Java APIs (JAX-RS, Spring REST, etc.)
– import & export main API languages
– generate Client SDKs, Server skeletons & HTML
 command line, based on APISpark capabilities
 APISpark (full stack PaaS)
– complete integration of Swagger tool chain (optimize)
– embed additional tool chains
– GitHub synchronization

25. 3) HANDS-ON LAB

26. YOUR STEPS
1. Sign in to APISpark
2. Craft a custom web API
3. Generate « API Commons » manifest
4. Display Swagger UI for your web API
 Follow this tutorial if you have a Restlet API
– http://restlet.com/learn/guide/2.3/extensions/apispark
– explains how to run the Restlet Introspector

27. KEEP IN TOUCH!
http://restlet.com
Twitter: @jlouvel
jlouvel@restlet.com
Restlet Platform
PaaS and Web API integration
Interview with Daniel Jacobson (Netflix)