Alfresco Web Scripts have become an important part of any Alfresco developer's tool kit and in this session we will take a deep dive into how Web Scripts can be used to provide public APIs for Alfresco extensions. After briefly reviewing the anatomy of a Web Script and discussing Alfresco's approach to Service development, we will work through an example that extends Alfresco with a simple service and creates a REST API using Web Scripts.
20. Document Description 12 Documentation URL templates (JSR-331) Response format details Authentication Transaction Lifecycle and family “Webscripts are declarative”
21. Controller 13 Optional Access to model Can read/write to repository Removes complexity from response template Implemented in JavaScript or Java Root objects set based on container “Controllers handle the request, gather information and populate the model.”
22. Response Template 14 Build web script response Implemented in Freemarker Many response templates per Webscript Access to model Root objects set based on container “Response templates format the response to a Webscript request.”
25. Alfresco Service API Architecture 17 Webscript API Javascript API Java Service API
26. Java Service API 18 Stateless Concise Provides all functionality Extendable Adaptable “The Java service layer is where all the ‘real’ code should go”
27. Java Script API 19 Object based Available in the repository Developer friendly Implemented in Java “The Java Script API helps rapid adoption and development of Alfresco applications”
28. Webscript Data API 20 REST(ful) Resource based Representations delivering data HTTP methods mapped to API Simple integration Public and remote “Webscript Data APIs unlock content.”
29. Design Example – Candy Store 21 “I want to create a Share customisation that allows me to manage the stock in my Candy Store. I should be able to see what stock is available, add/edit/remove the details of the stocked candy and review the stock levels.”
31. Design Considerations 23 Resources are referencable They have state The “things” in your API Collections Composite resources “Identifying resources in your API is key.” Resources
32. Design Example – Candy Store 24 Candy A candy bar that is currently stocked in the candy store. Candies A collection of all the candies currently stocked in the candy store. Candy Store The candy store it’s self. Candy Manager Manages the stock levels in the candy store. Usually use /api/actionQueue and custom actions instead. Resources
33. Design Considerations 25 HTTP methods should map logically to the API URLs should be composed of resources Parameters should be parameters Consistency is important No hard and fast rules “Simple always works best.” Methods & URLs
34. Case Study – Candy Store 26 CandyStore /candystore GET Candies /candystore/candies?restock={restock?} GET, POST Candy /candystore/candies/{productcode} GET, PUT, DELTE CandyManager /candystore/candymanager POST Methods and URLs
35. Design Considerations 27 A snap-shot of the state of a resource Sent to server in request Returned to client in response Multi-format XML/JSON/ATOM “Representations hold data transferred between client and server” Representations
37. Case Study – Candy Store 29 Webscript Definition Document
38. Implementation Considerations 30 JS API vs Fundamental API Repository vs Spring Runtime vs Compile Flexibility vs Concrete “No right or wrong answer, only what works best for you.” JavaScript vs Java Backed
39. Implementation Considerations 31 Extend BaseWebScriptTest Mock Webscript server Local and remote testing with same test code Test before you use “Untested API slows down application development” Unit testing
42. Learn More 34 wiki.alfresco.com forums.alfresco.com twitter: @AlfrescoECM
Editor's Notes
Where do we start? At the begining.Why do we have WebScripts?What are WebScripts used for?What is a WebScript?How do I use a WebScript?Where can I use a WebScript?
URL – unique resource locator.HTTP Methods – action to be performed on the resource (GET, PUT, POST and DELETE)HTTP Response Status – tells the client what’s happened (success, fail, event, action)Response types – the type of content being returned from the server (XML, HTML, JSON, ATOM)REST – Representational State TransferTODO – summarise the following into readable notes ...TODO – Diagram showing flow ... URL (method) -> Resource -> response (status) .. Transfer of representation .. Rest state .. REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of "representations" of "resources". A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.At any particular time, a client can either be in transition between application states or "at rest". A client in a rest state is able to interact with its user, but creates no load and consumes no per-client storage on the set of servers or on the network.The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used next time the client chooses to initiate a new state transition.[4]REST was initially described in the context of HTTP, but is not limited to that protocol. RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for applications based on the transfer of meaningful representational state. RESTful applications maximize the use of the pre-existing, well-defined interface and other built-in capabilities provided by the chosen network protocol, and minimize the addition of new application-specific features on top of it.
Web Script Runtime:A typical deployment includes an Alfresco Repository server hosting data Web Scripts with one or more Alfresco clients hosting presentation Web Scripts where communication between the two is over HTTP. The Alfresco Repository utilises the Servlet Run-time whereas a remote Web Client utilises the SURF Run-time for hosting Web Scripts. However, this is just one of many options given the following available Web Script Runtimes:Servlet Runtime (HTTP accessible)SURF Runtime (embed Web Script UI components in web-tier UI pages)JSR-168 Runtime (adapter between JSR-168 portlet API and Web Script)JSF Runtime (JSF tag to include Web Script)Facebook Runtime (access to Facebook API and Repository API within Web Script)We've already seen there are several types of Runtime available out-of-the-box. These Runtimes can be setup in conjunction with one the following out-of-the-box Containers:Presentation - a light-weight container for rendering User Interface components that can make service calls to remote data sources.Repository - a container for embedded use in the Alfresco Repository providing integration with transactions and direct access to content held in the Repository and services provided by the Repository.Flow:1. A request for a given URI arrives at the Web Script Runtime.2. The Runtime finds the appropriate Web Script for the URI. If one is found, the Runtime executes the Web Script but only after successfully authenticating first, if required. The first step of execution is to invoke the JavaScript bound into the Web Script.3. With JavaScript, you have access to a set of Alfresco services. When hosted within the Repository server you can search for information, navigate around the repository, modify information, create new documents, set properties on those documents, move data around, and delete data, plus access to all other Repository services. Outside of the Repository you can invoke remote services such as those by the Repository server.4. The results from the JavaScript are rendered using FreeMarker response templates. The response format may be one of HTML, ATOM, XML, RSS, JSON, CSV, or any combination of these. You must provide the appropriate templates.5. The Web Script Runtime sends the rendered results back via a response using the same protocol as the URI request.6. The Web Script client receives the response in the requested format.
Optional files – Controller, Configuration, Message Bundles, Response Status TemplateIn Alfresco repository or on JAVA classpath.4 predefined locations.Subfolders can be used to organise.Use refresh link on the /alfresco/service/ page to load new Web Scripts.