20140527 - apicon sf - workshop #2 - document and manage java-based web apis
DESCRIPTION
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 APITRANSCRIPT
![Page 1: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/1.jpg)
DOCUMENT AND MANAGEYOUR JAVA-BASED WEB API WITH APISPARK
Full stack PaaS for web APIshttp://apispark.com
May 27, 2014
Web API framework for Javahttp://restlet.com
![Page 2: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/2.jpg)
PRESENTERENTREPRENEUR 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
Twitter : @jlouvel
Blog : blog.restlet.com
![Page 3: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/3.jpg)
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
![Page 4: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/4.jpg)
1) OVERVIEW OF RESTLET PLATFORM
![Page 5: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/5.jpg)
WEB API PROJECTTYPICAL LIFE CYCLE
Create Host Manage Use Promote
1) Do It Yourself (DIY)
2) Platform as a Service (PaaS)
![Page 6: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/6.jpg)
WEB API FRAMEWORK FOR JAVAOPEN SOURCE SINCE 2005
6 editions44 extensions
1,5 M downloads100 000 developers
Version 2.2.0 launched in March 2014
Covers our ROA/DAPI guidelines
Consistent client & server APIPowerful routing & filtering
Comprehensive web securityAligned with REST & HTTP
Fast & scalable
![Page 7: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/7.jpg)
RESTLET FRAMEWORKSIX CONSISTENT EDITIONS, CLIENT & SERVER JAVA API
![Page 8: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/8.jpg)
APISPARKFULL STACK PAAS FOR WEB APIS
Send us your feed-back and help us making it the best PaaS for Web APIs !
![Page 9: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/9.jpg)
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)
![Page 10: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/10.jpg)
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
![Page 11: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/11.jpg)
COMPOSING APISPARK CELLS
Entity Store File Store
Custom API
Java iOS JS
HTTP HTTP
![Page 12: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/12.jpg)
STRUCTURE OF WEB APIS
API Contract
Implementation
Runtime
Web API
template
Completeweb API
HTTP HTTPS
![Page 13: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/13.jpg)
2) DOCUMENTING & MANAGING
Your Java-based web API
![Page 14: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/14.jpg)
CODE YOUR WEB APIIN JAVA LANGUAGE
JAX-RS API
Restlet API
Spring RESTSwagger
annotations
Bean Validationannotations
Google Cloud Endpoints API
1. Select
a main
Java API
Javasourcecode
3. Write your
Java code
JAXBannotations
2. Add extra
annotation
APIs
Jackson annotations
RESTfulWeb API
4. Get your
web API
![Page 15: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/15.jpg)
DOCUMENT YOUR WEB APIIN JAVA LANGUAGE
RESTfulWeb 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
APIBlueprint
Swagger
Google APIDiscovery
WADL
![Page 16: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/16.jpg)
DON’T GET LOCKED-INAPI 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
![Page 17: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/17.jpg)
DEMONSTRATION
![Page 18: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/18.jpg)
YOUR DASHBOARD
![Page 19: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/19.jpg)
LAUNCH INTROSPECTOR TOOLSUPPORTS RESTLET API, NEW JAVA APIS COMING
1) Launch fromyour IDE or the command line
2) Web API definition pushed
to APISpark
![Page 20: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/20.jpg)
DISPLAY YOUR WEB API DOCRELAUNCH INTROSPECTOR TO KEEP IN SYNC
![Page 21: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/21.jpg)
CHECK OUT API COMMONS TABWEB API MANIFEST BASED ON SWAGGER
![Page 22: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/22.jpg)
![Page 23: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/23.jpg)
CHECK OUT THE HOSTED SWAGGER UIEMBEDDED IN YOUR WEB SITE
![Page 24: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/24.jpg)
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
![Page 25: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/25.jpg)
3) HANDS-ON LAB
![Page 26: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/26.jpg)
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
![Page 27: 20140527 - APIcon SF - Workshop #2 - Document and manage Java-based web APIs](https://reader034.vdocuments.us/reader034/viewer/2022051816/546fe4e0b4af9fcd0a8b4583/html5/thumbnails/27.jpg)
KEEP IN TOUCH!
http://restlet.com
Twitter: @jlouvel
Restlet Platform
PaaS and Web API integrationInterview with Daniel Jacobson (Netflix)