still under construction, but feel free to explore :)
HOME / Articles/Tutorials / Android Articles/Tutorials / Tutorials on Android programming / Tutorials on Web and Web Services / Android and Web Services

Android and Web Services

Overview and comparison of the main SOA available, android web service client libraries and examples of WS integration.
Covering SOAP, XML-RPC, JSON(RPC), REST




This article is based on Android 4.3 API 18 and focuses mainly on HTTP as a transport for communicating between peers.

1. Overview of webservice technologies used

1.1 RPC

A remote procedure call (RPC) is an inter-process communication that allows a computer program to cause a subroutine or procedure to execute in another address space (commonly on another computer on a shared network) without the programmer explicitly coding the details for this remote interaction. That is, the programmer writes essentially the same code whether the subroutine is local to the executing program, or remote. When the software in question uses object-oriented principles, RPC is called remote invocation or remote method invocation.
We are going to discuss a few important RPC protocols used in Web Services and Mobile Apps.

1.2 XML-RPC

XML-RPC is a Remote Procedure Calling protocol that works over the Internet. An XML-RPC message is an HTTP-POST request. The body of the request is in XML. A procedure executes on the server and the value it returns is also formatted in XML.

HTTP Header Requirements:
  • A User-Agent and Host must be specified.
  • The Content-Type is text/xml.
  • The Content-Length must be specified and must be correct.
1.2.1 XML-RPC Data Types
XML-RPC can pass parameters of the following types:
  • four-byte signed integer: <i4> or <int>
  • boolean 0 (false) or 1 (true): <boolean>
  • string: <string>
  • double-precision signed floating point number: <double>
  • date/time: <dateTime.iso8601>
  • base64-encoded binary: <base64>
  • struct: <struct>
    
       
          OptionOne
          13
          
       
          OptionTwo
          133
          
       
                        
  • array: <array>
       
        
          11
          Egypt
          1
          -31.456
        
       
                        

Note: If no type is indicated, the type is string.

1.2.2 XML-RPC Request

A rpc call is represented by sending a Request to a Server. The Request has the following elements:

<methodCall>
The root element of the XML structure.
<methodName>
A string, containing the name of the method to be called. The string may only contain identifier characters, upper and lower-case A-Z, the numeric characters, 0-9, underscore, dot, colon and slash
<params>
In case the procedure call contains parameters.
<param>
A single parameter
<value>
The value of a param. It must have one of the defined data types
There is an example of XML-RPC Request:
                
   
    examples.getArticleTitle
      
        
         256
        
      
   
            
1.2.3 XML-RPC Response

When a rpc call is made, the Server, unless there's a lower-level error, always return 200 OK and reply with a Response . The Response is expressed as a single XML structure with the following members:

<methodResponse>
The root element of the Response XML structure.
<params>
In case the procedure call contains parameters.
<param>
A single parameter
<value>
The value of a param. It must have one of the defined data types
Here is an example of a successful XML-RPC Response
   
      
         
         Android and Web Services
         
      
   
                

1.2.4 XML-RPC Faulty Response

The Response can be a fault, which is also a single XML structure with the following members:

<methodResponse>
The root element of the Response XML structure.
<fault>
The fault container element which contains a value which is a struct with 2 elemnts faultCode(int) and faultString(string)
<value>
The value of a fault member. It must be int for faultCode or string for faultString.
Here is an example of a faulty XML-RPC Response

   
      
         
            
               faultCode
               347
               
            
               faultString
               No such article
               
            
         
      
   
                

1.3 SOAP

SOAP, originally defined as Simple Object Access Protocol, is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks. It relies on XML Information Set for its message format, and usually relies on other Application Layer protocols, most notably Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission.
SOAP is a successor of XML-RPC, however more complex to understand.
HTTP MIME Content-Type: application/soap+xml
1.3.1 SOAP Protocol
SOAP

The formal set of conventions governing the format and processing rules of a SOAP message. These conventions include the interactions among SOAP nodes generating and accepting SOAP messages for the purpose of exchanging information along a SOAP message path.

SOAP node

The embodiment of the processing logic necessary to transmit, receive, process and/or relay a SOAP message, according to the set of conventions defined by this recommendation. A SOAP node is responsible for enforcing the rules that govern the exchange of SOAP messages (SOAP Processing Model). It accesses the services provided by the underlying protocols through one or more SOAP bindings.

SOAP role

A SOAP receiver's expected function in processing a message. A SOAP receiver can act in multiple roles.

SOAP binding

The formal set of rules for carrying a SOAP message within or on top of another protocol (underlying protocol) for the purpose of exchange (see 4. SOAP Protocol Binding Framework). Examples of SOAP bindings include carrying a SOAP message within an HTTP entity-body, or over a TCP stream.

SOAP feature

An extension of the SOAP messaging framework (SOAP Extensibility Model). Examples of features include "reliability", "security", "correlation", "routing", and "Message Exchange Patterns" (MEPs).

SOAP module

A SOAP Module is a specification that contains the combined syntax and semantics of SOAP header blocks specified according to the rules in SOAP Modules. A SOAP module realizes zero or more SOAP features.

SOAP message exchange pattern (MEP)

A template for the exchange of SOAP messages between SOAP nodes enabled by one or more underlying SOAP protocol bindings (see SOAP Protocol Binding Framework). A SOAP MEP is an example of a SOAP feature (see SOAP Message Exchange Patterns (MEPs)).

SOAP application

An entity, typically software, that produces, consumes or otherwise acts upon SOAP messages in a manner conforming to the SOAP processing model (see SOAP Processing Model).

1.3.2 SOAP Data Encapsulation
SOAP message

The basic unit of communication between SOAP nodes.

SOAP envelope

The outermost element information item of a SOAP message.

SOAP header

A collection of zero or more SOAP header blocks each of which might be targeted at any SOAP receiver within the SOAP message path.

SOAP header block

An element information item used to delimit data that logically constitutes a single computational unit within the SOAP header. The type of a SOAP header block is identified by the XML expanded name of the header block element information item.

SOAP body

A collection of zero or more element information items targeted at an ultimate SOAP receiver in the SOAP message path ( SOAP Body).

SOAP fault

A SOAP element information item which contains fault information generated by a SOAP node.

1.3.3 SOAP Message Nodes
SOAP sender

A SOAP node that transmits a SOAP message.

SOAP receiver

A SOAP node that accepts a SOAP message.

SOAP message path

The set of SOAP nodes through which a single SOAP message passes. This includes the initial SOAP sender, zero or more SOAP intermediaries, and an ultimate SOAP receiver.

Initial SOAP sender

The SOAP sender that originates a SOAP message at the starting point of a SOAP message path.

SOAP intermediary

A SOAP intermediary is both a SOAP receiver and a SOAP sender and is targetable from within a SOAP message. It processes the SOAP header blocks targeted at it and acts to forward a SOAP message towards an ultimate SOAP receiver.

Ultimate SOAP receiver

The SOAP receiver that is a final destination of a SOAP message. It is responsible for processing the contents of the SOAP body and any SOAP header blocks targeted at it. In some circumstances, a SOAP message might not reach an ultimate SOAP receiver, for example because of a problem at a SOAP intermediary. An ultimate SOAP receiver cannot also be a SOAP intermediary for the same SOAP message (2. SOAP Processing Model).

1.3.4 SOAP Message Example

 
  
   1
   2013-09-13T11:00:00-05:00
  
 
 
  
   SOAP Learning
  
 

			    

1.4 JSON

JSON or JavaScript Object Notation, is a text-based open standard designed for human-readable data interchange. Derived from the JavaScript scripting language, JSON is a language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, JSON is language-independent, with parsers available for many languages.
1.4.1 JSON Data Types
  • Number - "articleid": 1234
  • String - "title": "Android Web Services"
  • Boolean - "published": true
  • Array - "tags": ["SOAP", "XML-RPC", "JSON", "REST"]
  • Object - "history": {"revision": 123, "author": "djodjo", ...}
  • Null - "otherinfo": null
1.4.2 Why JSON and not XML?
JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
The XML specification does not match the data model for most programming languages which makes it slow and tedious for programmers to parse. Compared to JSON, XML has a low data-to-markup ratio which results in it being more difficult for humans to read and write.

1.5 JSON-RPC

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.
HTTP POST Header Requirements:
  • Content-Type: MUST be application/json
  • Accept: MUST be application/json
  • The Content-Length must be specified and must be correct
1.5.1 JSON-RPC Data Types
Since using JSON the data types are the same as the JSON Data Types
1.5.2 JSON-RPC 2 Request

A rpc call is represented by sending a Request object to a Server. The Request object has the following members:

Examples:
                    {"jsonrpc": "2.0", "method": "addArticle", "params": ["Android and Web Services", "Android"], "id": 1}
                
				    {"jsonrpc": "2.0", "method": "addArticle", "params": {"title": "Android and Web Services", "category": "Android"}, "id": 2}
                    
                    {"jsonrpc": "2.0", "method": "removeArticle", "params": ["Android and Web Services", "Android"]}
                    
jsonrpc
A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
method
A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.
params
A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted if method does not require arguments. Params member can be of JSON Array or JSON Object types.
id
An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts

The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.

Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

If "id" is not specified then me request is considered as "Notification" and the Client will not expect a result nor should the Server send one.

1.5.3 JSON-RPC 2 Response

When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications. The Response is expressed as a single JSON Object, with the following members:

Examples:
                    {"jsonrpc": "2.0", "result": 123, "id": 1}
                
jsonrpc
A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
result
This member is REQUIRED on success.
This member MUST NOT exist if there was an error invoking the method.
The value of this member is determined by the method invoked on the Server.
error
This member is REQUIRED on error.
This member MUST NOT exist if there was no error triggered during invocation.
The value for this member MUST be an Object as defined in section 5.1.
id
This member is REQUIRED.
It MUST be the same as the value of the id member in the Request Object.
If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.

Either the result member or error member MUST be included, but both members MUST NOT be included.

1.5.4 JSON-RPC 2 Error Response

When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:

Examples:
                    {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}
                
                    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
                
code
A Number that indicates the error type that occurred.
This MUST be an integer.
message
A String providing a short description of the error.
The message SHOULD be limited to a concise single sentence.
data
A Primitive or Structured value that contains additional information about the error.
This may be omitted.
The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).

The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use. The error codes are nearly the same as those suggested for XML-RPC at the following url: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code message meaning
-32700 Parse error Invalid JSON was received by the server.
An error occurred on the server while parsing the JSON text.
-32600 Invalid Request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.
-32000 to -32099 Server error Reserved for implementation-defined server-errors.

The remainder of the space is available for application defined errors.

1.5.3 JSON-RPC 2 Batch Request-Response
The Client may send an Array filled with Request objects. The Server should respond with an Array containing the corresponding Response objects.
  • The number of objects returned SHOULD be the same as the number of requests except the "Notifications"
  • The results MAY be processed by the Server in any order and MAY be in any order within the returned array
  • If there is at least one JSON parsing error the Server rsponse MUST be a single Resonse object
  • If there is no value to be returned the Server MUST NOT return an empty array but nothing at all
Examples:
            -->        {"jsonrpc": "2.0", "method": "addArticle", "params": ["Android and Web Services", "Android"], "id": 1}
                       {"jsonrpc": "2.0", "method": "addArticle", "params": {"title": "Android and Web Services2", "category": "Android"}, "id": 2}
                       {"jsonrpc": "2.0", "method": "countArticles", "params": {"category": "Android"}, "id": 3}
                       
            <--        {"jsonrpc": "2.0", "result": 123, "id": 1}
                       {"jsonrpc": "2.0", "result": 1, "id": 3}
                       {"jsonrpc": "2.0", "result": 124, "id": 2}
                

Note that the "countArticles" method might be executed before the last "addArticle" and thus not give us any useful result. To be able to design independent Client and Server modules one must take into account the concurrency and include in a Batch call Requests which execution that does not depend on other Requests within the Batch array.

1.6 REST and RESTful

Representational State Transfer (REST) is an architectural style that abstracts the architectural elements within a distributed hypermedia system. REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements. REST has emerged as a predominant web API design model.

Putting it simple, REST requests are directed to resources (ex:http://web.djodjo.org/article/articles/android_articles/dev/web-and-services/web_services) using common set of verbs - the standard HTTP methods: POST(Create), GET(Retrieve), PUT(Update), DELETE(Delete). A request can contain and retrieve a representation of a resource which can be of any format: HTML, JSON, XML. The representation media format can be controlled by request HTTP Accept header and precified in the Server Response header.

1.6.1 REST Architecture Constraints and Properties
Client-Server
This simply means separation of concerns, meaning separating the user interface concerns from the data storage concerns. This leads to:
  • improving the portability of the user interface across multiple platforms
  • simplifying the server components
  • improving server scalability
  • client/server components can evolve independently (Internet-scale requirement of multiple organizational domains )
Stateless
client-server communication must be stateless in nature. This means that each request from client to server must contain all of the information necessary to understand the request. Client entirely keeps all session state information and no stored context is kept on the server.

This improves:
  • visibility - monitoring system does not have to look beyond a single request datum in order to determine the full nature of the request
  • reliability - eases the task of recovering from partial failures
  • scalability - the server does not need to manage and can quickly free resources

However it reduces:
  • network performance due to increasing the repetitive data sent in the requests
  • server's control over consistent application behaviour because the application becomes dependent on the correct implementation of semantics across multiple client versions
Cacheable
In order to improve communication speed a cache constraints are introduced into REST. This require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is labeled as cacheable then client can reuse that response later for equivalent requests.
This constraint can significantly reduce the number of interactions between the client and the server thus improve:
  • efficiency
  • scalability
  • user-perceived performance / client app responsiveness
However cache can also decrease reliability if stale data within the cache differs significantly from the data that would have been obtained from a fresh response from the server.
Uniform Interface
uniform interface between components is a typical feature of REST that distinguishes it from RPC.
This applied generality to the component interface improves:
  • visibility of interactions
  • overall system architecture complexity
  • independent evolvability of components due to decoupling of the implementations from the services they provide
This of course has also a negative effect on the efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs. REST is optimized for the common case of the Web - large-grain hypermedia data transfer, which might be not the best option for other architectures.
Layered System
This allows an architecture to be composed of hierarchical layers by constraining component behaviour such that each component cannot "see" beyond the immediate layer with which they are interacting. Intermediary layers may improve system scalability by enabling load-balancing and by providing shared caches, also enforcing security policies.
Code-On-Demand (optional)
This allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This clearly improves improves system extensibility however it reduces visibility, which is the reason why it is the only optional constraint in REST
1.6.2 REST interface constraints
As mentioned above REST must provide a uniform interface thus there are 4 interface constraints defined:
Identification of resources
REST uses a resource identifier to identify the particular resource involved in an interaction between components. A resource identifier can be URL, URN, URI. There should be only one predefined initial resource identifier.
Manipulation of resources through representations
To modify or delete the resource on the server a client needs just a representation of that resource, including its metadata(media type, last-modified time).
Self-descriptive messages
Each message includes enough information to describe how to process the message. The client does not need any prior information about what data to expect or how to parse that message. Standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.
Hypermedia as the engine of application state (HATEOAS)
all application state transitions must be driven only through actions that are dynamically identified within hypermedia by the server (e.g., by hyperlinks within hypertext). Except for an initial entry point, a client MUST not assume that any particular method is available for any particular resources beyond those received in representations from the server.
1.6.3 What is RESTful architectural style and REST API
For an architecture to be characterised as RESTful or an API to be called REST API it must conform to the 6 REST constraints described in 1.6.1, which includes also the 4 REST interface constraints in section 1.6.2
If a service violates any of the required constraints, it cannot be considered RESTful.
To use a RESTful service any client should not need more than the initial URI and set of standardized media types.
From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user's manipulation of those representations.

2. Comparison

2.1 Compare RPC vs REST

The root difference : REST implementations are hypermedia driven and decoupled from the services they provide
Note that some points can be positive or negative depending on the specific requirements of the system.
  • REST: client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia.
    RPC: clients and servers interact through a fixed interface

    +REST clients and servers can be implemented separately and evolve independantly
    +RPC more performance for specific narrow client range aimed services
  • REST: works mostly (only) on HTTP
    RPC: allow for the use of different transport protocols. Whats event more important is that it performs quite the same way on other protocols

    +REST http server based services
    +RPC various/fixed non hyper text protocol infrastructure

2.2 Compare SOAP vs RPC-XML vs RPC-JSON

This is just a comparison over diferent represantation schemes for communication antities (reposnse, request, error/exceptions).
When data is encoded in XML, the result is larger than an equivalent encoding in JSON, having that also XML-RPC uses about 4 times the number of bytes compared to plain XML to encode the same objects. Putting SOAP into the competition will not have any effect on the 1st and 2nd place just because of the verbose XML format SOAP has. Message Transmission Optimization Mechanism can be applied bust still it is the one with 'Simple' in the name that has much complexity added for just few improvements.
Although gzipping the responses/requests may lead to aslmost the same data json is still the one that is most human readable :)

2.3 Compare REST using XML vs JSON

This is more or less the same things with the RPC. Both XML and JSON are used to represnd some data. This data can have some schema definition which explains it or not. Nevertheless JSON has proved to be better for traffic, while there are quite a bit of already defined xml types. So its up to the system designer to decide what is important - rdefine new custom json formats or use arlready defined xml media formats

2.4 Conclusion

It is difficult to determine a definite winner as of course all depents on the specific needs of the system we are designing. Rest is preffered for multiple organizational domains with heavy hypermedia data transfer. Hypermedia might sound fancy but its nothing but a information set of plain text, hyperlinks, graphics, audio and video bundled together.
However if you aim at a service that should be accessible via different protocols and/or does not have an option to use HTTP as a protocol then the choice is obvious. This case however is rare as it is a fact that http is the least restrctect by firewalls and the most accepted protocol ever.

There is another consideration to make: Is is really worthed to change? Take for eaxmple Twitter's API is not RESTful at all. It doesn't have that pretty links neither and it has a huge documentation. Do they have the need to change make it Restful .. well not really, althought its not that hard, there is still some effort to be done.

Another important thing is that when we say client and server implementation are decoupled its not really the case ... well it is, but if you follow the standards. For example for a client to properly work it needs to know and accept as many Media Types as possible also the server needs to be able to send resonsenses formated in such a way. So the clent is not really just staying there not knowing anything but quite a bit of data.
This way wouldn't be more easier to just define some custom media types for the client and server that this is it? ... well of course it depends on what you want to achieve.

As regards to XML or JSON, JSON has proved to be better for traffic, while there are quite a bit of already defined xml types. So its up to the system designer to decide what is important.

Finnaly this is a topic that there can be quite abit of dicussion for 2 reasons:

  • A lot of peopple are using it (and abusing it) - THE WEB
  • There are quite abit of standard definitions in there, that all the abusers do not care to read and be compatible with
Both of those lead to huge discussion of whats right or wrong.

The truth is simple: A web service client and server can never be done fully independanly and decoupled they will always need to take into consideration some definitions, whether standarised or not there should be some.
As Roy says:

Of course the client has prior knowledge. Every protocol, every media type definition, every URI scheme, and every link relationship type constitutes prior knowledge that the client must know (or learn) in order to make use of that knowledge.

3.

9. Links

Author: DjoDjo