Successfully reported this slideshow.

RESTful web APIs (build, document, manage)

1,336 views

Published on

Web API course 2015

Published in: Technology
  • Be the first to comment

RESTful web APIs (build, document, manage)

  1. 1. « BUILD, DOCUMENT, MANAGE » CLASS RESTful Web APIs February 2015 @SteveSfartz
  2. 2. APIS ARE THE FUEL OF THE WEB APIGee 2015 – Web API Strategy
  3. 3. A BIT OF THEORY REST, web APIs, RESTful web APIs
  4. 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. 5. RICHARSON MATURITY MODEL martinfowler.com/articles/richardsonMaturityModel.html
  6. 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. 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. 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. 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. 10. FROM REST TO WEB APIS http://blog.restlet.com/2013/05/02/how-much-rest-should-your-web-api-get/
  11. 11. WEB APIS LIFE CYCLE design build host manage document promote … and version
  12. 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. 13. BUILD Do It Yourself with SAIL.JS
  14. 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. 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. 16. BUILD with the APISpark PaaS
  17. 17. APISPARK the first self-service platform for APIs http://restlet.com/products/apispark/features/
  18. 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. 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. 20. COMPOSING APISPARK CELLS Entity Store File Store Custom API Java iOS JS HTTP HTTP
  21. 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. 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. 23. MONITOR with Runscope
  24. 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. 25. HOL 3 • Monitoring with RunScope – import your POSTMAN collection • Traffic Inspector > Import Requests – create test – run – add assertions – schedule
  26. 26. DOCUMENT YOUR WEB API Swagger, RAML, APIBlueprint
  27. 27. HOW ? • Top down : create manually or via an editor • Bottom up : code annotations, introspection • No standardization – Swagger – RAML – API-blueprint – …
  28. 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. 29. COMPARISON SmartBear 2014
  30. 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. 31. BOTTOM UP APPROACH Document via Annotations or Introspection
  32. 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. 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. 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. 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. 36. MANAGE YOUR WEB API
  37. 37. HOW IT WORKS • Reverse proxy in front of your API – Filter incoming calls – Authentication, Authorizations – Firewall – Analytics – …
  38. 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. 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. 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. 41. BUILD / FINE-GRAINED CONTROL with the Restlet Framework
  42. 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. 43. HOL 9 • load the web API reference implementation – https://github.com/restlet/restlet-tutorial • run org.restlet.tutorial.WebApiTutorial • invoke via POSTMAN
  44. 44. API DESIGNS a bit of architecture
  45. 45. WEB API ARCHITECTURE • basic design – no distinction between app and backend – the app is the sum of data and UX app data
  46. 46. WEB API ARCHITECTURE • « api-aware » design – multiple apps, multiple devices, need to evolve independently app dataapiapp
  47. 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. 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. 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. 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

×