WEB-API - dis.uniroma1.itberaldi/MACC_16/slides/WebAPI.pdfXML in a nutshell • An XML document ......

WEB-API

Remote Procedure Call principle

RPC protocolexternal data representation

Client code

Stub

local call

Process A

Server code

Skelethon

local call

Process B

RPC over Internet (HTTP)

Client code Server code

RPC protocol = HTTPData representation=JSON/XML

Web-API• Based of RPC over HTTP• Two main external data representations

• JSON• XML

• Several protocols• REST

• Derived from RESTful implementation of a web service, but simpler• JSONP

• Used from JS• JSON-RPC

• 1.0, 1.1, 2.0• XML-RPC

• Oldest• SOAP (web services)

• Bold ones are ‘standard’ for mobile applications

JSON types

JSON• Two fundamental structures:

See JSON Lint(validator)

XML in a nutshell • XML (eXtensible Markup Language) is a language derived

from SGML (Standard Generalized Markup Language),from which HTML also derives.

• The key notion in the markup language familty is amarkup, something that describes some aspect of thedata

• In HTML markups define the appearance of thedocument, whereas in XML they define the meaning ofthe data

XML in a nutshell• An XML document is a tree

• Data appear inside elements

• An element not only contains the data itself but alsoinformation describing the meaning of the data

Example

Il Signore degli Anelli, di John Ronald Reuel Tolkien,

Bompiani.

Title

Author

Editor

Example<book>

<title> Il Signore degli Anelli

</title><author>

John R. R. Tolkien</author><editor>

Bompiani</editor>

</book>

Title

Author

Editor

Book Elements

Tips : Browser allows to see the structure of the document

Elements and attribute<title>

Il Signore degli Anelli</title>

Data

Tag

<title pages=“345”> Il Signore degli Anelli

</title>

Attribute (key/value pair)

Well formed document

Valid document• Document that follows composition rules about their

structure• Two solutions• Document Type Definition

• Easier, less ‘powerful’

• XML Schema• More complex, more powerful

WFD and validation

XMLDocument

Syntax check

Semantic check

Grammar

HTTP request• An HTTP request consists of: a request method (verb), resource

URL, header fields (metadata), body (data)

• HTTP 1.1 defines 9 request methods, among which:

• GET: Retrieves the resource identified by the request URL• POST: Sends data of unlimited length to the URL

• PUT: Stores a resource under the request URL• DELETE: Removes the resource identified by the request URL

• HTTP 1.0 includes only the GET, HEAD, and POST methods.

Protocols that use JSON• REST like protocols• JSON-RPC

• 1.0, 1.1, 2.0

• JSONP

REST-like requests• Simplest form of RPC over Internet protocol• Method calls are mapped to HTTP request (GET/POST)• Method name is a parameter of the call• Reply is formatted as JSON or XML data• Name is derived from «RESTful Web service»

• Resources are identified through URI• Stateless protocol• CRUD operations (Create,Read,Update,Delete) mapped to HTTP

verbes (POST,GET,PUT,DELETE)

Example

…

http://api.wunderground.com/api/http://api.wunderground.com/api/http://api.wunderground.com/api/http://api.wunderground.com/api/KEYKEYKEYKEY////FEATUREFEATUREFEATUREFEATURE/[/[/[/[FEATUREFEATUREFEATUREFEATURE…]/q/…]/q/…]/q/…]/q/QUERYQUERYQUERYQUERY....FORMATFORMATFORMATFORMAT

Features

geolookup conditions forecast

types= JSON, XML

JSON-RPC • Request format:

• method - A String with the name of the method to be invoked.• params - An Array of objects to be passed as parameters to the

defined method.• id - A value of any type, which is used to match the response with

the request that it is replying to.

• Response format:• result - The data returned by the invoked method.

• If an error occurred while invoking the method, this value must be null.

• error - A specified error code if there was an error invoking the method, otherwise null.

• id - The id of the request it is responding to

Example• --> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}• <-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

• Notifications are possible (id not set or equal to null)

Some example from JSON-RPC 2.0 --> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

-->{"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

-->{"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}<-- {"jsonrpc": "2.0", "result": 19, "id": 4}

call batch --> [

{"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},{"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},{"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},{"foo": "boo"},{"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},{"jsonrpc": "2.0", "method": "get_data", "id": "9"} ]<-- [{"jsonrpc": "2.0", "result": 7, "id": "1"},{"jsonrpc": "2.0", "result": 19, "id": "2"},{"jsonrpc": "2.0", "error": {"code": -32600, "message": "InvalidRequest."}, "id": null},{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method notfound."}, "id": "5"},{"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}]

JSONP• Used from JavaScript• Response returns the JSON data, with JavaScript code

(usually a function call) wrapped around it. • This "wrapped payload" is then interpreted by the browser

as a JS call.

Examplehttp://api.wunderground.com/api/[API_KEY]/conditions/q/rome.json

….http://api.wunderground.com/api/[API_KEY]/conditions/q/rome.json?callback=f

JSONP

Example: Geocoding API

Example: Geocoding API (json)

Example: Geocoding API (xml)

Example: reverse Geocoding (json)

Example: Reverse geocoding (xml)

Example of XML replyhttp://api.wunderground.com/api/[APIKEY]/conditions/q/zmw:00000.1.16240.xml

Interoperability

Chrome Developer tool

Technologies for web-API from a mobile

• Mobile applications usually use REST-like requests plus JSON data representation

• In android this can be implemented from inside the application code itself• We have already seen some example in previous lessons• Fast

• …Or from a webView using JavaScript• Slower, but in some case it is enough

Options using JavaScript• Static JS code• Dynamic JS Code• Library (e.g., jQuery)• AJAX

• The goal of these solutions is the same:• To load a JSON-encoded object from a server using GET HTTP

request

Static call (JSONP)

<html>

<headl>

<script>

</script>function process

<body>

</body></html>

</script>

</head>

<scriptsrc=‘http://….&callback=process’>

Example from the browser

Example of static call

Dynamic call • In the previous example the call is made as soon as the

page is loaded• Now we see how to make the call in response to a user

event (click a button)• This pattern is already kwown:

• Define the visual object ‘button’• Add a listener to the onclick event• Make the call from the listener• In the following example the call is made from an element that is

addedd at runtime

Example

Make a call from jQuery• jQuery is one popular JS library that simplifies

programming• It contains a simple method to make a call

Example

AJAX• The last option we study is to use AJAX• AJAX makes asynchronous call

Asynchronous RPC: AJAX

Example

XML-RPC

Overview of XML-RPC• Data Model

• Scalar• Struct• Array

• Messages• Request message• Response message• Error message

Scalar types

Tag Type Example

<i4> or <int> four-byte signed integer -12

<boolean> 0 (false) or 1 (true) 1

<string> string hello world

<double> double-precision signed floating point number

-12.214

<dateTime.iso8601> date/time 20101504T09:30:00

<base64> base64-encoded binary eW91IGNhbid0IHJlYWQgdGhpcyE=

Struct type

<struct><member>

<name>lowerBound</name><value><i4>18</i4></value>

</member>

<member><name>upperBound</name><value><i4>139</i4></value>

</member></struct>

Array type

<array><data>

<value><i4>12</i4></value><value><string>Egypt</string></value><value><boolean>0</boolean></value><value><i4>-31</i4></value>

</data></array>

Request message

• Root element: methodCall• contains a MethodName element and a paramselement

• MethodName contains the name of the procedure being called

• Params is a list of values for the parameters

Example<?xml version="1.0"?>

<methodCall>

<methodName>XXX</methodName>

<params>

<param>

<value><i4>123</i4></value>

</param>

<param>

<value><double>12.3</double></value>

</param>

</params>

</methodCall>

Example<?xml version="1.0"?>

<methodCall>

<methodName> XXX</methodName>

<params>

<param>

<value><i4>123</i4></value>

</param>

<param>

<value><double>12.3</double></value>

</param>

</params>

</methodCall>

methodCall

XXX

methodName

params

param value i4

param value double

123

12.3

Example<?xml version="1.0"?>

<methodCall>

<methodName>Scuola XXX</methodName>

<params>

<param>

<value><i4>123</i4></value>

</param>

<param>

<value><double>12.3</double></value>

</param>

</params>

</methodCall>

methodCall

XXX

methodName

params

param value i4

param value double

123

12.3

methodNameparams

paramparam

doublei4

methodCall

Complete request messagePOST /xmlrpc HTTP 1.0User-Agent: …Host: …Content-type: text/xmlContent-length: ..

<?xml version=“1.0”?><methodCall><methodName>Circle_Area</methodName><params><param><value><double>12.2</double></value><param><params></methodCall>

Reply message

<?xml version="1.0"?>

<methodResponse>

<params>

<param>

<value><i4>1</i4></value>

</param>

</params>

</methodResponse>

Fault message<?xml version="1.0"?><methodResponse>

<fault><value>

<struct><member>

<name>faultCode</name><value><int>4</int></value></member>

<member><name>faultString</name><value><string>Too many parameters.</string></value></member>

</struct></value>

</fault></methodResponse>

Example: Flickr ®

Flickr: request, reply message format

http://api.flickr.com/services/xmlrpc/

http://api.flickr.com/services/soap/

WEB-API

http://api.flickr.com/services/rest/

Example: rest call

Example

• Reply is wrapped through jsonFlickrApi callback name• To avoid this, set nojsoncallback=1 option

json format

Relationship with cloud computing

• Standard web browsing (HTTP+uman)• Programmatic access (Rest,JSON-RPC,etc.)

Programmatic Service Access(many methods)

Web URL (standard HTTP methods)

web browerHTTP

Application

HTTP Rest,XML-RPC,etc

Service

PaaSIaaS

SaaS

Types of Cloud Computing

(IaaS) Infrastructure as a Service

(SaaS)Software as a Service

XaaS (PaaS) Platform as a Service

Web-API

Ex: Google docs

Allows for developing applications

Offers Virtual Machines

Relationship with web services

SERVICE

INT

ER

FAC

E

--------------------------------

Interface definition (e.g., WSDL)

Technology A

Technology B

Technology C

Web services• Represent an established and common medium for

sophisticated, web-based service logic. The technologiesexploited in a WS are

• WSDL (Web Service Definition Language)• Markup language used to define the API of the WS

• XML Schema• Define the structure of the data being exchanged

• SOAP• Request/Reply protocol for message exchange

• UDDI (Universal Description,Discovery,Integration)• Register where WSDL description can be published and retrived

Web Service

WSDL

SOAPXML

Schema

UDDI

define types and payload structure for

Enable discovery of