webscripts
DESCRIPTION
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.TRANSCRIPT
1
Webscripts
Roy WetherallSenior Software Engineer, Alfresco
twitter: @rwetherall
2
Agenda
•Where to start?•Nuts and Bolts•Building a Webscript Data API•Questions
3
Where to start?
At the beginning ...
4
What is a Webscript?
In no more than 140 characters ...
5
What can Webscripts be used for?
• Presentation• Data• Integration
“Webscripts unlock content”
6
Fundamental Concepts
A
Y
X
Req
uest
Res
pons
e
Process
Wait
HT
TP
GEThttp://myserver/A/X
200<x>My Content</x>
7
Webscript Execution Flow
8
Webscript Architecture
9
Nuts and Bolts ...
... of a Webscript
10
Webscript Files
•Description document•Controller•Response template•Configuration•Message bundles•Response status template
“Place files on the classpath or in the repository”
11
Document Description
• Documentation• URL templates (JSR-331)• Response format details• Authentication• Transaction• Lifecycle and family
“Webscripts are declarative”
12
Controller
• 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.”
13
Response Template
• 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.”
14
Simple Webscript Example
15
Building a Webscript Data API
16
Alfresco Service API Architecture
Java Service API
Javascript API
Webscript API
17
Java Service API
• Stateless• Concise• Provides all functionality• Extendable• Adaptable
“The Java service layer is where all the ‘real’ code should go”
18
Java Script API
• Object based• Available in the repository• Developer friendly• Implemented in Java
“The Java Script API helps rapid adoption and development of Alfresco applications”
19
Webscript Data API
• REST(ful)• Resource based• Representations delivering data• HTTP methods mapped to API• Simple integration• Public and remote
“Webscript Data APIs unlock content.”
20
Design Example – Candy Store
“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.”
21
Design Example – Candy Store
Content Model and Java API
22
Design Considerations
• Resources are referencable• They have state• The “things” in your API• Collections• Composite resources
“Identifying resources in your API is key.”
Resources
23
Design Example – Candy Store
• 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
24
Design Considerations
• 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
25
Case Study – Candy Store
• CandyStore• /candystore• GET
• Candies • /candystore/candies?restock={restock?}• GET, POST
• Candy• /candystore/candies/{productcode}• GET, PUT, DELTE
• CandyManager• /candystore/candymanager• POST
Methods and URLs
26
Design Considerations
• 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
27
Design Exercise – Candy Store
{“productcode” : “alf123”,“title” : “Wham Bar”,“description” : “Sticky, fizzy chew bar.”,“wholesaleprice”: 0.25,“saleprice” : 0.5,“stockcount” : 14,“restocklevel” :5
}
Representations
28
Case Study – Candy Store
Webscript Definition Document
29
Implementation Considerations
• 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
30
Implementation Considerations
• 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
31
Java Backed Webscripts
32
Questions
33
Learn Morewiki.alfresco.comforums.alfresco.comtwitter: @AlfrescoECM