JSON Web Services

yazooalbumSecurity

Nov 3, 2013 (3 years and 9 months ago)

134 views

JSON Web Services


Details


Print

Tags:

json

web services

jsonwebservice

Table of Contents

[
-
]



1 Registering JSON Web Services



2 List available JSON Web Services



3 More on registration



3.1 Ignoring a method



3.2 HTTP method name and URL



3.3 Manual registration mode



4 JSON Web Service Invocation



4.1 Passing parameters as part of URL path



4.2 Passing parameters as URL query



4.3 Mixed w
ay of passing parameters



4.4 Difference between URL and query encoding



4.5 Sending files as arguments



4.6 JSON RPC



5 Returned values

The idea behind JSON Web Services is to provide portal service methods as JSON API. This makes services
methods easily accessible using HTTP request not only from portals javascript, but also from any JSON
-
speaking
client out ther
e.

This is not a new idea and the portal

already contains an implementation

that allows users calling services. This time
we went one step further and developed an enhanced
and more convenient and developer
-
friendly solution.

There are three parts of JSON Web Services functionality: registration, invocation and results. Each part will be
discussed in more details.

Registering JSON Web Services

#

To register some service methods as a JSON Web Services, user has to annotate the

*ServiceImpl

class
with
@JSONWebS
ervice

annotation. By doing this,

all

service methods of the class becomes available as JSON
Web Services.

And that’s all! Upon start, portal scans all classes on classpath for annotation usage (don’t worry, portal scans raw
class content, so only classes
of interest are loaded, not all of them). Each class that uses this annotation is
examined, registered and all its methods becomes exposed as JSON API.

For example, let’s annotated

DLAppServiceImpl
:

@JSONWebService public class DLAppServiceImpl extends DLA
ppServiceBaseImpl { ...

Deploy and (re)start the portal. Notice the following lines in console output:

10:55:06,595 DEBUG [JSONWebServiceConfigurator:121
] Configure JSON web service actions
10:55:06,938 DEBUG [JSONWebServiceConfigurator:136] Configuring 63 actions in 454 ms

At this point, registration is done and all

DLAppServiceImpl

service methods are registered as JSON Web Services.

List available JSON

Web Services

#

To overview and verify what service methods are registered and available, user can use following

URL to list them all
in browser (notice the ‘
jsonws
’ in the URL, it is relevant for all JSON Web Services calls
-

more on invocation later):

http://localhost:8080/tunnel
-
web/jsonws/dump

The result is a simple HTML table, showing following data: HTTP meth
od name, web service relative URL path and
registered service method. By default, HTTP method name is

GET

for all methods which name starts with ‘get’, ‘is’ or
‘has’; otherwise, method is

POST.

JSON web service relative URL path is formed from service clas
s name and from
method name, by converting a camel
-
case name into the lowercased separated
-
by
-
dash name. For our example,
some of the mappings in our example are:

POST/dlapp/add
-
file
-
entry
c.l.portlet.documentlibrary.service.DLAppServiceUtil#addFileEntry(r
epositoryId,
folderId, title, description, changeLog, bytes, serviceContext) GET /dlapp/get
-
file
-
entries
c.l.portlet.documentlibrary.service.DLAppServiceUtil#getFileEntries(repositoryId,
folderId)

More on registration

#

User can control registration and mapping process using annotation elements.

Ignoring a method

#

To ignore a method from an exposed service class, just annotated method with:

@JSONWebService(mode = JSONWebServiceMode.IGNOR
E)

Such methods will be not available as JSON api.

HTTP method name and URL

#

As expected, it is also possible to
define custom HTTP method name and URL names, using the same annotation.

@JSONWebService(value = "add
-
file
-
wow", method = "PUT") public FileEntry addFileEntry(

In this example, method

addFileEntry

will be mapped to

/dlapp/add
-
file
-
wow


(actually to the:

/tunnel
-
web/jsonws/dlapp/add
-
file
-
wow
) and can be accessed using HTTP method

PUT
.

If URL name starts with a slash character (‘
/
’), only method name is used to form service URL; class name is ignored.

@JSONWebService("/add
-
something
-
very
-
specific") public F
ileEntry addFileEntry(

Similarly, user can change the class name part of the URL, by setting the value in class
-
level annotation:

@JSONWebService("dla") public class DLAppServiceImpl extends DLAppServiceBaseImpl {

Now all service methods would have '
dla
'

in the URL instead of default '
dlapp
'.

Manual registration mode

#

Up to now, it is expected that most of the service methods is going to be exposed and allowed user to ignore few. But
sometimes user wants a different behavior: to explicitly specify only methods that are going to be exposed. This is
possible, too, using s
o
-
called manual mode on class
-
level annotation; or simply by not using any class level
annotation. Either way user then annotates only methods that has to be exposed.

public class DLAppServiceImpl extends DLAppServiceBaseImpl { @JSONWebService public
FileE
ntry addFileEntry(

JSON Web Service Invocation

#

Registered JSON web services can be invoked in several ways.

Passi
ng parameters as part of URL path

#

Parameters can be passed as part of the URL path. After the service URL
(defined by class and method annotations,
as we've seen above) user can append method parameters (name/value pairs). Parameter names are formed form
method argument names, by converting camel
-
case to lowercased separated
-
by
-
dash name. Example:

http://localhost:8080/tunnel
-
web/secure/jsonws/dlapp/get
-
file
-
entries/repository
-
id/10172/folder
-
id/0

Parameters may be given in

any

order; it’s not necessary to follow arguments order as defined by methods.

When some method name is overloaded, the best m
atch will be used
-

a method that contains the least of arguments
undefined.

Passing parameters as URL query

#

Pa
rameters can be passed as request parameters, too. The difference is that now parameter names are equals to
service method argument names:

http://localhost:8080/tunnel
-
web/secure/jsonws/dlapp/get
-
file
-
entries?repositoryId=10172&folderId=0

Everything else
remains the same, like order is not important, etc

Mixed way of passing parameters

#

Parameters can be passed in
mixed way: some can be part of the URL path and some can be specified as request
parameters.

Difference between URL and query encoding

#

This is something often forgotten: there is a difference between URL and query (request parameters) encoding. Most
illustrable difference is how space character is encoded. When space is part of the URL path it is encoded a
s

%20
,
when it is part of the query it is encoded as plus sign (
+
).

Sending files as arguments

#

Files can be uploade
d using multipart forms and request. Example

<form action="http://localhost:8080/tunnel
-
web/secure/jsonws/dlapp/add
-
file
-
entry"
method="POST" enctype="multipart/form
-
data"> <input type="hidden" name="repositoryId"
value="10172"/> <input type="hidden" name=
"folderId" value="0"/> <input type="hidden"
name="title" value="test.jpg"/> <input type="hidden" name="description" value="File
upload example"/> <input type="hidden" name="changeLog" value="v1"/> <input
type="file" name="file"/> <input type="submit" value
="addFileEntry(file)"/> </form>

JSON RPC

#

JSON Web Service may be invoked using

JSON RPC
. Good

part of JSON RPC 2.0 specification is supported.
Parameters may be passed only as named parameters, since positional are not supported
-

there are too many
overloaded method for convenient use of positional parameters. Example:

POST http://localhost:8080/
tunnel
-
web/secure/jsonws/dlapp {"method":"get
-
folders",
"params":{"repositoryId":10172, "parentFolderId":0}, "id":123, "jsonrpc":"2.0"}

Returned values

#

No matter which way invoked, JSON web services return JSON string that represents service method result.
Returned object is
loosely serialized

to JSON string and returned to calling client.


0 Attachments

557 Views

Average (2 Votes)

Comments

Showing 3 Comments


Jay Patel

5/30/11 11:31 PM

Nice Wiki....can't wait to have my hands on it..


Thiago Leão Moreira

5/31/11 10:45 AM

There is a missing part on the registration process. By default, without any further configuration, Liferay does not pick
up the classes that has the annotation @JSONWebService in your portlet project. You must configure the "JSON
Web Service Servlet" in t
he web.xml file to get your classes scanned and configured. I tested using revision r82143 of
trunk


AA CC

6/8/11 3:50 AM

Hi Thiago Leão Moreira, i have a problem with @JSONWebService, eclipse can find it. But i can understand what i

had to do to solve this problem.

TK