webscripts

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