WebService [How-To]

dany_dev · March 2011

Since that webservice is a hot topik on the forum, I decided to write a guideline to understand what you can do when you need to use webservice from iOS (so iphone or ipad or ipod, etc...)

INDEX:

Section 1: About Webservice
Section 2: REST webservice
Section 3: SOAP Webservice
Section 4: HTTP Request
Section 5: Parse XML
Section 6: Parse JSON

In the first Section we will see some basic things about webservice, in Section 2 and 3 we will see 2 important architectures of webservice and how we can use these. In section 4 we will see some example to communicate with webservice, and in section 5 and 6 we will see how we can use what the webservice return.

Section 1: About Webservice

What is a WebService?

Basically is a server that expose methods, you can call these methods with an input and you will receive an output. A webservice can be written in any language (php, C#, VB.Net, Java, Python, etc...).
Really webservices are much more than that, but this is not the place to study the argument in dept.
In iOS SDK there isn't a framework for consume webservice, so you need to create something from scratch, this can be "easily" done because webservice generally support HTTP + XML or JSON (in some case HTTP is not enabled for default, you need to enable manually yourself).

What is WSDL?

WSDL is a file that describe in depth the webservice (so contain a list of methods, with detail for their input and output, more other stuff)

What is XML?

XML Is a standard way to represent data in textual format.

What is JSON?

JSON is another standard way to represent data in textual format.

What is SOAP, and REST?

SOAP and REST are 2 architectures of webservice. The first use SOAP messages (subset of XML) to communicate with webservice, so you will use http requests to send\receive SOAP messages to communicate with the webservice. With REST you can use http requests using GET (or POST, PUT, DELETE) to call a method of webservice, and XML or JSON as input and output.

There are many other things to know about webservices, start reading from the link posted above if you want have a good explanation of the topik.

Usefull links (tutorials + other stuff):
http://www.iphonedevsdk.com/forum/iphone-sdk-development/2841-resolved-how-call-soap-service.html
iPhone SDK: First Steps With JSON Data Using the Twitter API
Tutorial: JSON Over HTTP On The iPhone | Mobile Orchard
JSON Framework for iPhone (Part 2)
iPhone Programming Tutorial ? Intro to SOAP Web Services | iPhone Programming Tutorials
http://github.com/akosma/iPhoneWebServicesClient
Consuming XML Web Services in iPhone Applications
http://www.raywenderlich.com/2965/how-to-write-an-ios-app-that-uses-a-web-service

NOTE1: This tutorial is not intended to be a perfect explanation of webservice (so some term and phrase can be not 100% exact), it is just a guideline to consume webservice with iOS SDK.
NOTE2: My english is not so good, so if you find some error, tell me privately, i will fix it.
NOTE3: Feel free to add some usefull informations (links, approaches, utility, etc...), I will try to keep updated the thread with all options possible.

dany_dev · March 2011

Section 2: REST webservice
REST is the easier to consume, it generally have a link, where you can specify a method and parameter directly with GET (GET mean inserting parameters directly on the link) Example: http://www.server.net/rest/?method=myMethod&par1=ok
So what you need to use a REST webservice is just to know the link with the right method and right input for that and then you will call it using an http request. [Look Section 4: HTTP Request]

You can decide also to use some specifics libraries to consume REST WebService
HTTPRiot HTTPRiot: HTTPRiot - A simple HTTP REST Library
ObjectiveResource iPhone on Rails and ObjectiveResource; Making communication between the iPhone and a Rails web-service pain-free.
These have the aim to make even easier consume a REST webservice, HTTPRiot support JSON, ObjectiveResource support XML and JSON, and both came with some samples to start using it.

Section 3: SOAP webservice
I will show you 2 way to understand how you can create right SOAP Messages.

1) Software that generate code:

SudzC is one of these,
Link: SudzC (alpha) | clean source code from your web services

It is a great tool that generate objective-c code ready to use, starting from WSDL (WSDL is a complete description of webservice, so in it you can read input\ouput of all webservice methods)
Recently was not updated often but the developer said that he will update soon his project adding new features and fixing bugs.
it can work, or can produce something that not fully work. Try it and see if you have some problems. In this case, you can try search on the forum to find some thread about sudzc.

Another software is wsdl2objc, but avoid it, is too pre-alpha and moreover outdated.
Link: wsdl2objc - Generates Objective-C (Cocoa) code from a WSDL for calling SOAP services - Google Project Hosting

2) Create "manually" xml to send with HTTP request and parse XML that you receive

With this solution, you should create the classes that represent the objects that your method(s) need (you can also start from the classes generated by sudzc). and then you will create a http request to your webservice, it will reply with an xml to parse.

What you want try to do is call some method of your webservice, so you need to understand what webservice expect to have when you call that method and what the webservice will return as output (so that you can parse it). You can read this information looking at the WSDL, but sometime when webservice is not easy\little, can be hard to fully understand what you need directly from WSDL.

So, you can use soapUI, it can help you a lot.

1)download soapUI
2)file\new soap project, and insert link to your wsdl
3)expand method that you want launch, double click "Request", you will see the xml that you should produce to call method.
4)recreate it manually on your iphone (concatenating strings and variables)
5)Send in post to your webservice link asynchronously (you can use ASIHTTPRequest or NSURLConnection). [Look Section 4: HTTP Request]
6)The server will reply with another xml that you can parse. [Look Section 5: Parse XML]

Another way to know what you need to send in xml, is too use a sniffer (wireshark? fiddler? tcpmon?) and see the xml that your "standard client" send\receive (assuming that you have a working client), and then use it as described in points 4,5,6.

dany_dev · March 2011

Section 4: HTTP Request
How you can do a HTTP request? Easy, using NSURLConnection or ASIHTTPRequest.
For REST webservice generally you need just to do a request to the link (generally using just GET to specify input).
For SOAP webservice generally you need to do a request to the link of your webservice and add your SOAP Message in POST (that contain the method to call and the input for that method)

You would do the request asynchronously, seen that you want to do the request in background without block User Interface, so now we will see how to do asynchronous http requests with NSURLConnection and with ASIHTTPRequest.

NOTE:
NSURLConnection is built in with iOS SDK so you don't need to include nothing to use it, ASIHTTPRequest is a third party library that allow you to easily use http request and more stuff related. In order to use it in your project you must follow this ASIHTTPRequest Setup Instructions

Using ASIHTTPRequest for WebService (when you don't need to specify an input in POST)


-(void)callWebService{
   //this is a typical url for REST webservice, where you can specify the method that you want to call and the parameters directly with GET
   NSURL *url = [NSURL URLWithString:@\"http://www.yourserver.net/webservice/rest/?method=myMethod&par1=ok\"];
   ASIHTTPRequest *request = [ASIHTTPRequest requestWithURL:url];
     
   [request setDidFinishSelector:@selector(requestCompleted:)];
   [request setDidFailSelector:@selector(requestError:)];
   
   [request setDelegate:self];
   [request startAsynchronous];
}
 
- (void)requestCompleted:(ASIHTTPRequest *)request
{
   NSString *responseString = [request responseString];
}
 
- (void)requestError:(ASIHTTPRequest *)request
{
   NSError *error = [request error];
}

How you can know the name of the methods and their parameters?
Check if your webservice have a WSDL or WADL, or check the documentation (generally who offer a webservice create also a documentation)

Using ASIHTTPRequest for Webservice (when you need to specify an input using POST)


-(void)callWebService{
   NSURL *url = [NSURL URLWithString:@\"http://www.yourserver.net/webservice\"];
   ASIHTTPRequest *request = [ASIHTTPRequest requestWithURL:url];
    
    NSString *yourPOSTstring = [NSString stringWithFormat:@\" write here your SOAP Message or JSON input (depend on your webservice)\"];

   [request appendPostData:yourPOSTstring];

   [request setDidFinishSelector:@selector(requestCompleted:)];
   [request setDidFailSelector:@selector(requestError:)];
   
   [request setDelegate:self];
   [request startAsynchronous];
}
 
- (void)requestCompleted:(ASIHTTPRequest *)request
{
   NSString *responseString = [request responseString];
}
 
- (void)requestError:(ASIHTTPRequest *)request
{
   NSError *error = [request error];
}

What you need to insert in yourPOSTstring? A SOAP Message o a JSON string that contain your input (depend on what expect your webservice)

Now that you are able to call your webservice and retrieve its response, you just need to parse it, [Look Section 5: Parse XML] or [Look Section 6: Parse JSON]

NOTES:
Your REST WebService need to use PUT?


[request appendPostData:yourPUTstring];
[request setRequestMethod:@\"PUT\"];

Your REST WebService need to use DELETE?


[request appendPostData:yourDELETEstring];
[request setRequestMethod:@\"DELETE\"];

dany_dev · March 2011

Using NSURLConnection (async) WebService (when you don't need to specify an input using POST)

YourViewController.h

#import < UIKit/UIKit.h>

@interface YourViewController : UIViewController {
	NSMutableData *dataWebService;
}

YourViewController.m


#import \"YourViewController.h\"

@implementation YourViewController

- (void)viewDidLoad
{
    [super viewDidLoad];
    
    dataWebService = [[NSMutableData data] retain];
    
    NSMutableURLRequest *request = [[NSMutableURLRequest requestWithURL:[NSURL URLWithString:@\"http://www.yoursite/webService\"]] retain];
    
    NSURLConnection *myConnection = [NSURLConnection connectionWithRequest:request delegate:self];
    
    [myConnection start];    
    
}


- (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response {
    [dataWebService setLength:0];
}

- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data {
    [dataWebService appendData:data];
}

- (void)connectionDidFinishLoading:(NSURLConnection *)connection {
    
    NSString *responseString = [[NSString alloc] initWithData:dataWebService encoding:NSUTF8StringEncoding];
    
    NSLog(@\"Response: %@\",responseString);
    
    [responseString release];
    
    [dataWebService release];

}

- (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error {
    NSLog(@\"Eror during connection: %@\", [error description]);
}

Then in connectionDidFinishLoading, we have responseString, the output of our webservice.

Using NSURLConnection (async) WebService (when you need to specify an input using POST)

The code is really similar, we just need some changes to add POST.

YourViewController.h

#import < UIKit/UIKit.h>

@interface YourViewController : UIViewController {
	NSMutableData *dataWebService;
}

YourViewController.m


#import \"YourViewController.h\"

@implementation YourViewController

- (void)viewDidLoad
{
    [super viewDidLoad];
    NSString *yourPostString = [NSString stringWithFormat:@\" write here your SOAP Message or JSON input (depend on your webservice)\"];
    
    dataWebService = [[NSMutableData data] retain];
    
    NSMutableURLRequest *request = [[NSMutableURLRequest requestWithURL:[NSURL URLWithString:@\"http://www.yoursite/webService\"]] retain];

    NSString *postLength =  [NSString stringWithFormat:@\"%d\", [yourPostString length]];
    
    [request addValue:@\"text/xml; charset=utf-8\" forHTTPHeaderField:@\"Content-Type\"];

    [request addValue:postLength forHTTPHeaderField:@\"Content-Length\"];    

    [request setHTTPMethod:@\"POST\"];
   
    [request setHTTPBody:[yourPostString dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLConnection *myConnection = [NSURLConnection connectionWithRequest:request delegate:self];
    
    [myConnection start];    
    
}


- (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response {
    [dataWebService setLength:0];
}

- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data {
    [dataWebService appendData:data];
}

- (void)connectionDidFinishLoading:(NSURLConnection *)connection {
    
    NSString *responseString = [[NSString alloc] initWithData:dataWebService encoding:NSUTF8StringEncoding];
    
    NSLog(@\"Response: %@\",responseString);
    
    [responseString release];
    
    [dataWebService release];

}

- (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error {
    NSLog(@\"Eror during connection: %@\", [error description]);
}

Then in connectionDidFinishLoading, we have responseString, the output of our webservice, you just need to parse it, [Look Section 5: Parse XML] or [Look Section 6: Parse JSON]

dany_dev · March 2011

Section 5: Parse XML

Now that we have a response from the server, generally we want to parse it to create an object of the class that represent the object(s) returned.

We will see how to do that with an example.

Suppose that we have a webservice method getUser(id) that return the information about a user giving an id.
So the responseString from webservice when we call that method will be something like this:


< env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
	< env:Header>
	< /env:Header>
	< env:Body>
		< ns2:getUserResponse xmlns:ns2=\"http://remote.myServer.it/\">
			< return username=\"dany_dev\">
				< password_md5>DKLJASDSA123123HASDASJKH12AKLSDJ121< /password_md5>
				< numPost>140< /numPost>
				< friends>
					< friendName>mike< /friendName>
					< friendName>paul< /friendName>
					< friendName>andrea< /friendName>
				< /friends>
				< banned>false< /banned>
			< /return>
		< /ns2:getUserResponse>
	< /env:Body>
< /env:Envelope>

Nice, so we have the following class that represent it

WS_User.h


#import < Foundation/Foundation.h>

@interface WS_User :NSObject
{
	NSString* username;
	NSString* password_md5;
	int numPost;
	NSMutableArray* arrFriends;
	bool banned;
	
}

@property (retain, nonatomic) NSString* username;
@property (retain, nonatomic) NSString* password_md5;
@property (retain, nonatomic) NSMutableArray* arrFriends;

@end

let me show the code to parse it

ParserUser.h


#import < Foundation/Foundation.h>
#import \"WS_User.h\"

@interface ParserUser : NSObject  <NSXMLParserDelegate>{

	NSXMLParser   *revParser; 
	
	WS_User *userRet;
	
	NSMutableString *currentElement;
	
}

-(WS_User*)parseUser:(NSString *)xml;
@end

ParserUser.m


#import \"ParserUser.h\"
#import \"WS_User.h\"

@implementation ParserUser

-(WS_User*)parseUser:(NSString *)xml{

	userRet = [[[WS_User alloc] init] autorelease]; ;

	
	NSData* data=[xml dataUsingEncoding:NSUTF8StringEncoding];

	
	revParser = [[NSXMLParser alloc] initWithData:data];
	
	[revParser setDelegate:self];
	[revParser setShouldProcessNamespaces:NO];
	[revParser setShouldReportNamespacePrefixes:NO];
	[revParser setShouldResolveExternalEntities:NO];
	[revParser parse]; 
    
	[revParser release];
	
	return userRet; 

}


- (void) parser: (NSXMLParser *) parser parseErrorOccurred: (NSError *) parseError {
	NSLog(@\"Error Parser:%@\",[parseError localizedDescription]);
}

- (void) parser: (NSXMLParser *) parser didStartElement: (NSString *) elementName
   namespaceURI: (NSString *) namespaceURI
  qualifiedName: (NSString *) qName
  attributes: (NSDictionary *) attributeDict{
	
	if ([elementName isEqualToString:@\"return\"]) {
		userRet.dsUsername = [attributeDict objectForKey:@\"username\"];
	}


	if ([elementName isEqualToString:@\"friends\"])
	{
		NSMutableArray *tmpArr = [[NSMutableArray alloc] init];
		userRet.arrFriends = tmpArr;
		[tmpArr release];
	}

	
}

- (void) parser: (NSXMLParser *) parser didEndElement: (NSString *) elementName
   namespaceURI: (NSString *) namespaceURI
  qualifiedName: (NSString *) qName{  
	

		
		if ([elementName isEqualToString:@\"password_md5\"]) {
			userRet.password_md5 = currentElement;
		} else if ([elementName isEqualToString:@\"numPost\"]) {
			userRet.numPost = [currentElement intValue];
		}else if ([elementName isEqualToString:@\"banned\"]) {
			userRet.banned = [currentElement boolValue];
		}
		
		
		if ([elementName isEqualToString:@\"friend\"]) {
			[userRet.arrFriends addObject:currentElement];
		}

		
		[currentElement release];
		currentElement = nil;
	
}

- (void) parser: (NSXMLParser *) parser foundCharacters: (NSString *) string{
		
	if(!currentElement)
		currentElement = [[NSMutableString alloc] initWithString:string];
	else
		[currentElement appendString:string];
			
}


@end

This example cover various situations (when you need to parse an int\boolean, or an array of value (like friends, an array of strings) or a value that is on an attribute (like username)
Nice, so now we should just call this



- (void)requestCompleted:(ASIHTTPRequest *)request
{
   NSString *responseString = [request responseString];
   ParserUser *pu = [[ParserUser alloc] init];
   WS_User *myUser = [pu parseUser:responseString];	
   [pu release];
}

We should have our user in myUser, now starting from that you should be able to make a parser for your objects.

NOTE:
When a WebService return an error, return a particular object: SoapFault, so you should create a SoapFault object and a SoapFaultParser that parse your responseString searching for a SoapFault, and when you are sure that responseString is not a fault, you should call ParserUser to parse the string as a WS_User.
I haven't done it in this tutorial just to keep it simple, you can see some code to do it from sudzc generated code, or you can just create it starting from my example.

dany_dev · March 2011

Section 6: Parse JSON

In the same manner of xml section, we will se an example for JSON parsing.

But first we need to see how to setup project to use it, because there is any JSON framework included with iOS SDK,
1) you need to download here SBJson
2) add all the files on folder "Classes" with Drag&Drop on your project, (select the "Copy items into destination group’s folder" option)

Now you should only import SBJson.h in your class.

    #import \"SBJson.h\"

Suppose that we have a webservice method getUser(id) that return the information about a user giving an id.
So the responseString from webservice when we call that method will be something like this:


{\"return\":
 {
  \"username\": \"dany_dev\",
  \"password_md5\": \"DKLJASDSA123123HASDASJKH12AKLSDJ121\",
  \"numPost\": \"140\"
  \"friends\" :
    [
      {\"friendName\": \"mike\"},
      {\"friendName\": \"paul\"},
      {\"friendName\": \"andrea\"}
    ]
  \"banned\": \"false\"
 }
}

Now the code to parse it.


- (void)requestCompleted:(ASIHTTPRequest *)request
{
    NSString *responseString = [request responseString];
   
    NSDictionary *dictionary = [responseString JSONValue];  
    
    NSDictionary *dictionaryReturn = (NSDictionary*) [dictionary objectForKey:@\"return\"];


    NSString *pass = (NSString*) [dictionaryReturn objectForKey:@\"password_md5\"];
    NSLog(@\"password: %@\", pass);
    
    int numPost = [[dictionaryReturn objectForKey:@\"numPost\"] intValue];
    NSLog(@\"numPost: %d\", numPost);
    

    NSArray *arrFriends = (NSArray*) [dictionaryReturn objectForKey:@\"friends\"];
    
    for(int n=0;n<[arrFriends count];n++){
    
        NSDictionary *dictionaryArr = (NSDictionary*) [arrFriends objectAtIndex:n];

        NSString *friend = (NSString*) [dictionaryArr objectForKey:@\"friendName\"];
        
        NSLog(@\"Friend Name:%@\",friend);
    }

}

Explanation:
responseString contain our json output returned by server, to parse it, we just need to call the method JSONValue, this return a NSDictionary with all the values.
dictionary is a NSDictionary, in our case it have 1 element, that element is in "return" key and is another NSDictionary. We assigned that to dictionaryReturn.
dictionaryReturn contain 5 objects (4 string: username, password_md5, banned, numPost and 1 NSArray). The array contain 3 NSDictionary each with 1 String on it (with key friendName), so we need to loop on the array, take the NSDictionary and then take the NSString from that.

NOTE:
Since that our webservice return only info about 1 user, we have a NSDictionary returned, if webservice return more than a user, it would returned a NSArray, so we would used


    NSArray *arrUsers = [responseString JSONValue];

and so we would looped on the array that contain X NSDictionary, each representing a single user.

Finally you can fill your classes that represent the user (WS_User), or you can use directly what JSON Framework returned, as you prefer!.

dany_dev · April 2011

new part posted ;)

dany_dev · April 2011

tutorial completed!
Enjoy.

dudeofswim · April 2011

That's awesome! Thanks!

zachynek · April 2011

dany_dev;321540 said:
tutorial completed!
Enjoy.

Cool tutorial, thanks very much. I just came up with another related question bit more to PHP. Let's say I have index.php which loads me data from DB, creates JSON and does ECHO (something like here: http://app.vapa.cz/). But then...every user can easily see those data from DB. How would you protect it from others???

My idea is that iOS creates a HTTP request which will include some kind of parameter like user name and password. Then my index.php page will check this name + pass whether user is allow to dig data and if so, index.php will make him JSON. Is that good way or is there something better???

THX

dany_dev · April 2011

yes, including always a user\pass can be a solution, but with a sniffer can be discovered.

skgammon3 · April 2011

Thank you so much dany_dev, very helpful. Is there any way you could post the file source code or send them via email? I'm still confused about how these files should be set up in xcode. For example, where would the "envelope" script be located?

Thanks again!

dany_dev · April 2011

skgammon3;329457 said:
Thank you so much dany_dev, very helpful. Is there any way you could post the file source code or send them via email? I'm still confused about how these files should be set up in xcode. For example, where would the "envelope" script be located?

Thanks again!

For now i haven't an example ready, also if i'm planning to do it one soon (within May).

The xml to send to webservice (soap message that contain envelop, etc...), can be for example on a file, so that you can retrieve it, and add information on it.

jpsubbarayalu · May 2011

Valuable tutorial!!!Its awesome!!!

Thank you so much...

Midnight · May 2011

Thanks a lot, that is a great tutorial!

lolozaur · May 2011

Man, thanks a lot. Now all I have to do is understand all this things in order to develop it further.

famictech2000 · July 2011

Hello

I have a website with java as the back end and jsp as the front end , and mysql as the database. I am trying to follow youe tutorial which looks great but can anyone tell me can this tutorial be used if I do not use SOAP or REST.

Can I make the resquest the same way to the http to my jsp page that accesses the jsp and intefaces with the database adn send out a request?

thanks in advance.

tianzhen99 · July 2011

Try this site: Tabilet, build remote data service for mobile developers , then you can jump to step 6 directly.

If you already have a SOAP setup, then use SOAP; otherwise, RESTful http is much easier to go. Make sure you return a JSON data set (or XML) and the "Content-Type" header in your return is "application/json".

Also, make sure you put proper authentication on who can call request which data.

famictech2000;354235 said:
Hello

I have a website with java as the back end and jsp as the front end , and mysql as the database. I am trying to follow youe tutorial which looks great but can anyone tell me can this tutorial be used if I do not use SOAP or REST.

Can I make the resquest the same way to the http to my jsp page that accesses the jsp and intefaces with the database adn send out a request?

thanks in advance.

dany_dev · July 2011

famictech2000;354235 said:
Hello

I have a website with java as the back end and jsp as the front end , and mysql as the database. I am trying to follow youe tutorial which looks great but can anyone tell me can this tutorial be used if I do not use SOAP or REST.

Can I make the resquest the same way to the http to my jsp page that accesses the jsp and intefaces with the database adn send out a request?

thanks in advance.

Yes, you can do the same exact thing, you just need a php or equivalent (so jsp is ok) script that give result in xml or json. Then you can follow "Section 4: HTTP Request" to call it and obtain the response. and then follow Section 5-6 to parse it.

nignesh · August 2011

Thank you so much..its awesome tutorial !!!

its cover all,from ABC of webservice...

its very useful to me...thanx :)

rickideeuk · August 2011

This has been a great help and introduction to webservices, thanks very much.

There is one thing I'm struggling with though ASIHTTPRequest and JSON...

If I use...
NSString *pass = (NSString*) [dictionaryReturn objectForKey:@"password_md5"];
NSLog(@"password: %@", pass);

How do I then get that *pass string into a UILabel called *nameone?

I've tried all kinds on versions based around
nameone.text = pass

But nothing seems to work, I just get a blank label.

Any help would be brilliant.

Many Thanks

dany_dev · August 2011

please create another thread for your issue, it is not related in any mode with webservice....

rickideeuk · August 2011

Sorry Dany I'll do that now :)

jagds · August 2011

Its very useful tutorial..
Thanks... Deny...

trongdth · August 2011

@dany_dev: have u ever try to connect a webservice security? It seems till now we cannot do that. Do u have any suggestion?

dany_dev · September 2011

trongdth;367186 said:
@dany_dev: have u ever try to connect a webservice security? It seems till now we cannot do that. Do u have any suggestion?

give me an example of WebService security, i will take a look......ASIHTTPRequest should handle it.

Howdy, Stranger!

Forums

WebService [How-To]

Replies