Webscripts
Download as PPTX, PDF3 likes2,219 views
The document provides an overview of webscripts, focusing on their architecture, implementation, and usage in data APIs within the Alfresco platform. It covers key concepts such as response templates, controllers, and design considerations for building a webscript data API, using a candy store example for illustration. Additionally, it suggests best practices for testing and emphasizes the importance of consistency in design.
Webscripts
- 1. Webscripts2Roy WetherallSenior Software Engineer, Alfrescotwitter: @rwetherall
- 4. Building a Webscript Data API
- 5. QuestionsWhere to start?4At the beginning ...
- 6. What is a Webscript?5In no more than 140 characters ...
- 7. What can Webscripts be used for?6Presentation
- 8. Data
- 10. Fundamental Concepts7GEThttp://myserver/A/XWaitRequestResponseHTTPProcess200<x>My Content</x>AXY
- 13. Nuts and Bolts ...10... of a Webscript
- 15. Controller
- 17. Configuration
- 18. Message bundles
- 19. Response status template“Place files on the classpath or in the repository”
- 20. Document Description12DocumentationURL templates (JSR-331)Response format detailsAuthenticationTransactionLifecycle and family“Webscripts are declarative”
- 21. Controller13OptionalAccess to modelCan read/write to repositoryRemoves complexity from response templateImplemented in JavaScript or JavaRoot objects set based on container“Controllers handle the request, gather information and populate the model.”
- 22. Response Template14Build web script responseImplemented in FreemarkerMany response templates per WebscriptAccess to modelRoot objects set based on container“Response templates format the response to a Webscript request.”
- 23. Simple Webscript Example 15
- 24. Building a Webscript Data API16
- 25. Alfresco Service API Architecture17Webscript APIJavascript APIJava Service API
- 26. Java Service API18StatelessConciseProvides all functionalityExtendableAdaptable“The Java service layer is where all the ‘real’ code should go”
- 27. Java Script API19Object basedAvailable in the repositoryDeveloper friendlyImplemented in Java“The Java Script API helps rapid adoption and development of Alfresco applications”
- 28. Webscript Data API20REST(ful)Resource basedRepresentations delivering dataHTTP methods mapped to APISimple integrationPublic and remote“Webscript Data APIs unlock content.”
- 29. Design Example – Candy Store21“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.”
- 30. Design Example – Candy Store22Content Model and Java API
- 31. Design Considerations23Resources are referencableThey have stateThe “things” in your APICollectionsComposite resources“Identifying resources in your API is key.”Resources
- 32. Design Example – Candy Store24CandyA candy bar that is currently stocked in the candy store.CandiesA collection of all the candies currently stocked in the candy store.Candy StoreThe candy store it’s self.Candy ManagerManages the stock levels in the candy store.Usually use /api/actionQueue and custom actions instead.Resources
- 33. Design Considerations25HTTP methods should map logically to the APIURLs should be composed of resourcesParameters should be parametersConsistency is importantNo hard and fast rules“Simple always works best.”Methods & URLs
- 34. Case Study – Candy Store26CandyStore/candystoreGETCandies /candystore/candies?restock={restock?}GET, POSTCandy/candystore/candies/{productcode}GET, PUT, DELTECandyManager/candystore/candymanagerPOSTMethods and URLs
- 35. Design Considerations27A snap-shot of the state of a resourceSent to server in requestReturned to client in responseMulti-format XML/JSON/ATOM“Representations hold data transferred between client and server”Representations
- 36. Design Exercise – Candy Store28{“productcode” : “alf123”,“title” : “Wham Bar”,“description” : “Sticky, fizzy chew bar.”,“wholesaleprice”: 0.25,“saleprice” : 0.5,“stockcount” : 14,“restocklevel” :5}Representations
- 37. Case Study – Candy Store29Webscript Definition Document
- 38. Implementation Considerations30JS API vs Fundamental APIRepository vs SpringRuntime vs CompileFlexibility vs Concrete“No right or wrong answer, only what works best for you.”JavaScript vs Java Backed
- 39. Implementation Considerations31Extend BaseWebScriptTestMock Webscript serverLocal and remote testing with same test codeTest before you use“Untested API slows down application development”Unit testing
- 41. Questions33
Editor's Notes
- #5: 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?
- #8: 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.
- #9: 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.
- #12: 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.