Web services tutorial

Lorna Mitchell

• PHP Consultant/Developer/Trainer

• API Specialist

• Author and Speaker

• Open Source Project Lead (http://joind.in)

• Twitter: @lornajane

• Site: http://lornajane.net

2

Agenda

• Web Services and a Simple Example

• HTTP and Data Formats

• Consuming Services from PHP

• Service Types and Soap

• RPC Services

• Building RESTful services

Code samples at: http://bit.ly/fE0f6f

3

What Is A Web Service?

• Means of exposing functionality or data

• A lot like a web page

• Integration between applications

• Separation within an application

5

Web Services and You

This is not rocket science

You already know most of what you need!

6

Architecture Using APIs

Common to use an API internally as well as exposing it

7

Building Blocks

You can make an API from any tools you like

• Existing MVC setup

• Simple PHP (as in these examples)

• Framework module

• Component library

9

My First Web Service

• Make a virtual host

• e.g. http://api.local
• Don’t forget to restart apache
• Add an entry to your hosts ﬁle

<VirtualHost *:80>
ServerName api.local
ServerAdmin admin@localhost
DocumentRoot /var/www/myapi/public

<Directory /var/www/myapi/public>
AllowOverride All
Order deny,allow
Allow from All
</Directory>
</VirtualHost>

api.vhost
10

My First Web Service

• Create the index.php ﬁle

• e.g. /var/www/myapi/public/index.php

$data = array(
'format' => 'json',
'status' => 'live'
);
echo json_encode($data);

public/index.php

11

Consume Your Service

• curl http://api.local

• For more information about curl:

• http://curl.haxx.se/
• http://bit.ly/esqBmz

12

JSON JavaScript Object Notation

• Originally for JavaScript

• Native read/write in most languages

• Simple, lightweight format - useful for mobile

• In PHP we have json_encode and json_decode

• These work with arrays and objects

Our service returns:
{'format':'json','status':'live'}

13

Heartbeat Method

• A method which does nothing

• No authentication

• Requires correct request format

• Gives basic feedback

• Shows that service is alive

14

Delivering A Web Service

• Service

• Documentation

• Examples

• A help point

If you’re only going to build the service, don’t bother

15

HTTP

HTTP is Hypertext Transfer Protocol - we’ll recap on some key elements:

• Status Codes (e.g. 200, 404)

• Headers (e.g. Content-Type, Authorization)

• Verbs (e.g GET, POST)

17

Status Codes

A headline response. Common codes:

200 OK
302 Found
301 Moved
401 Not Authorised
403 Forbidden
404 Not Found
500 Internal Server Error

Consumers can get a WIN/FAIL indicator before unpacking the response
in full

18

Working with Status Codes in PHP

We can observe status codes with curl, passing the -I switch
curl -I http://api.local

Let’s amend our web service, to return a 302 header
header("302 Found", true, 302);

$data = array(
'format' => 'json',
'status' => 'live'
);

19

HTTP Verbs

• More than GET and POST

• PUT and DELETE to update and delete in a RESTful service

• HEAD, OPTIONS and others also speciﬁed

GET Read
POST Create
In REST, we use:
PUT Update
DELETE Delete

20

HTTP Headers

Headers are the metadata about the content we send/receive

Useful headers:

• Accept and Content-Type: used for content format negotiation

• User-Agent: to identify what made the request

• Set-Cookie and Cookie: working with cookie data

• Authorization: controlling access

21

Accept Header

What type of content can the consumer understand?

• -v with curl to see request and response headers

• -H to add headers

curl -v -H "Accept: text/html" http://api.local

Gives the output:
* About to connect() to api.local port 80 (#0)
* Trying 127.0.0.1... connected
* Connected to api.local (127.0.0.1) port 80 (#0)
> GET / HTTP/1.1
> User-Agent: curl/7.21.0 (i686-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0
> Host: api.local
> Accept: text/html
>

22

Using the Accept Header

We can work out what format the user wanted to see from the Accept
header.
$data = array(
'status' => 'live',
'now' => time()
);

if(false !== strpos($_SERVER['HTTP_ACCEPT'], 'text/html')) {
echo "<pre>";
print_r($data);
echo "</pre>";
} else {
// return json
}

public/headers.php

23

Content-Type Header

The Content-Type header: literally labels the contents of the response.
We can include these in our examples:
$data = array(
'status' => 'live',
'now' => time()
);

if(false !== strpos($_SERVER['HTTP_ACCEPT'], 'text/html')) {
header('Content-Type: text/html');
echo "<pre>";
print_r($data);
echo "</pre>";
} else {
// return json
header('Content-Type: application/json');
}

public/headers.php

24

Handling XML Formats

We can work with XML in PHP almost as easily

• Content type is text/xml or application/xml

• Two XML libraries in PHP

• SimpleXML bit.ly/g1xpaP
• DOM bit.ly/e0XMzd

• Give consumers a choice of formats

25

Adding XML to Our Service

$data = array(
'status' => 'live',
'now' => time()
);

$simplexml = simplexml_load_string('<?xml version="1.0" ?><data />');
foreach($data as $key => $value) {
$simplexml->addChild($key, $value);
}

header('Content-Type: text/xml');
echo $simplexml->asXML();

The result is this:
<?xml version="1.0"?>
<data><status>live</status><now>1302981884</now></data>

26

How to REALLY Handle Accept Headers

Example accept header (from my browser)
text/html, application/xml;q=0.9, application/xhtml+xml,
image/png, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1

• See a much nicer example of this in headers-accept.php

• Taken almost entirely from the source of arbitracker

• http://arbitracker.org
• src/classes/request/parser.php

• Try this from curl, setting your own headers, and from your browser

27

Versions and Formats

• Always include a version parameter or media type

• Handle multiple formats, by header or parameter

• JSON
• XML
• HTML
• ?

• Common to detect header, allow parameter override

28

Statelessness

• Request alone contains all information needed

• No data persistence between requests

• Resource does not need to be in known state

• Same operation performs same outcome

29

Consuming Your First Web Service

Three ways to consume web services:

• Via streams (e.g. ﬁle_get_contents and some context)

• Using the curl extension

• bit.ly/h5dhyT

• Using Pecl_HTTP

• bit.ly/g4CfPw

31

Using File_Get_Contents

This is the simplest, useful for GET requests
$response = file_get_contents('http://api.local/');
var_dump($response);

You can set more information in the stream context bit.ly/gxBAgV

32

Using Curl

This extension is commonly available
$ch = curl_init('http://api.local/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Look out for the CURLOPT_RETURNTRANSFER; without it, this will echo
the output

33

Using Pecl_HTTP

This is the most powerful and ﬂexible, and can easily be installed from
http://pecl.php.net
$request = new HTTPRequest('http://api.local/', HTTP_METH_GET);
$request->send();
$response = $request->getResponseBody();

Strongly recommend pecl_http if you are able to install pecl modules on
your platform

34

Web Service Types

There are a few types of web service

• RESTful

• RPC (Remote Procedure Call)

• XML-RPC
• JSON-RPC
• Soap

36

RPC Services

These services typically have:

• A single endpoint

• Method names

• Method parameters

• A return value

A familiar model for us as developers

37

Soap

• Not an acronym

• (used to stand for Simple Object Access Protocol)

• Special case of XML-RPC

• VERY easy to do in PHP

• Can be used with a WSDL

• Web Service Description Language

38

Soap Example: Library Class

class Library {
public function thinkOfANumber() {
return 42;
}

public function thinkOfAName() {
return 'Arthur Dent';
}
}
/public/soap/Library.php

39

Publishing a Soap Service

(don’t blink or you will miss it!)

include('Library.php');

$options = array('uri' => 'http://api.local/soap');
$server = new SoapServer(NULL, $options);
$server->setClass('Library');

$server->handle();

/public/soap/index.php

40

Consuming a Soap Service

To call PHP directly, we would do:
include('Library.php');

$lib = new Library();
$name = $lib->thinkOfAName();
echo $name; // Arthur Dent

Over Soap:
$options = array('uri' => 'http://api.local',
'location' => 'http://api.local/soap');
$client = new SoapClient(NULL, $options);

$name = $client->thinkOfAName();
echo $name; // Arthur Dent

41

Pros and Cons of Soap

• Many languages have libraries for it

• .NET and Java programmers in particular like it

42




• Weird things happen between languages regarding data types

42





• When it works, it’s marvellous

• When it doesn’t work, it’s horrid to debug (so I’ll show you how)

42





• When it works, it’s marvellous

• When it doesn’t work, it’s horrid to debug (so I’ll show you how)

• WSDL is complicated!

42

Working with WSDLs

WSDL stands for Web Service Description Language

• WSDLs were not designed for humans to read

• They are written in XML, and are very verbose

• If you do need to read one, start at the END and read upwards in
sections

• Soap uses very strict data typing, which is an unknown concept in
PHP

Read about WSDLs: bit.ly/eNZOmp

43

Debugging Soap

The Soap extension has some debug methods:

• Set the options to include trace=1 in the SoapClient

• getLastRequest(), getLastRequestHeaders(),
getLastResponse(), getLastResponseHeaders() are then
available

For all web service types, you can use:

• I like Wireshark (http://www.wireshark.org)

• Others use Charles (http://www.charlesproxy.com)

• If you like reading XML then use curl

• SoapUI (http://soapui.org)

44

Wireshark Demo

Bear with me while I ﬁre up wireshark to show you

45

Consistency

• Important to retain

• Naming conventions
• Parameter validation rules
• Parameter order

• Just as you would in library code

47

The Action Parameter

As a simple place to start, let’s add an action parameter.
// route the request (filter input!)
$action = $_GET['action'];
$library = new Actions();
$data = $library->$action();

/rpc/index.php

Here’s the code for the Actions class
class Actions {
public function getSiteStatus() {
return array('status' => 'healthy',
'time' => date('d-M-Y'));
}
}

/rpc/actions.php

So try http://api.local/rpc/index.php?action=getSiteStatus
48

Small APIs

• Beware adding new functionality

• Simple is maintainable

• Easy to use and understand

49

Adding an Action

To add a new action, create a new method for the Actions class, returning
an array to pass to the output handlers
public function addTwoNumbers($params) {
return array('result' => ($params['a'] + $params['b']));
}

/rpc/actions.php

But how do we pass the parameters in? Something like this
$action = $_GET['action'];
$library = new Actions();
// OBVIOUSLY you would filter input at this point
$data = $library->$action($_GET);

/rpc/index.php

50

Access Control

A few common ways to identify users

• Username and password with every request

• Login action and give a token to use

• OAuth

• For internal applications, ﬁrewalls

51

RPC Service Example: Flickr

Take a look at http://www.flickr.com/services/api/

• Supports multiple formats (for request and response)

• Is well-documented and consistent

• Has libraries helping users to consume it

• Offers both RPC and RESTful (kind of!) interfaces

• Follows true XML-RPC (see
http://en.wikipedia.org/wiki/Xml-rpc)

Vast numbers of applications using this API to provide ﬂickr functionality
elsewhere

52

RPC vs REST

We’ve seen an RPC service, but what about REST? The two are quite
different

• RPC services describe protocols, e.g. XML-RPC

• RPC is a familiar: functions and arguments

• REST is a set of principles

• Takes advantage of HTTP features

• Typically has "pretty URLs", e.g. Twitter is mostly RESTful

53

REST

• REpresentational State Transfer

• URLs are unique resource identiﬁers

• HTTP verbs indicate which operation should happen

• We have full CRUD operations on a series of resources

Here’s one I prepared earlier: /public/rest/

55

REST as a Religion

Beware publishing a service labelled "RESTful"

• Someone will always tell you it isn’t

• They are probably right

• The strict rules around REST sometimes ﬁt badly around business
requirements

• Flamewars will ensue

Instead: "An HTTP Web Service"

56

Making Our Service Restful

We’re aiming for URLs that look something like this:

• http://api.local/rest/user

• http://api.local/rest/user/3

• http://api.local/rest/user/3/friends

A speciﬁc item is a resource; where you request a list, e.g. /user, this is
called a collection

57

All Requests to index.php

We want to push all requests through index.php, there is an .htaccess ﬁle
that does this
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 [L]
</IfModule>

/public/rest/.htaccess

58

Routing Within Our App

So our routing depends on the URL and on the verb used, so our
controllers have a method per verb:

• GET /user

• Becomes UserController::GETAction()

$verb = $_SERVER['REQUEST_METHOD'];
$action_name = strtoupper($verb) . 'Action';
$url_params = explode('/',$_SERVER['PATH_INFO']);
$controller_name = ucfirst($url_params[1]) . 'Controller';
$controller = new $controller_name();
$data = $controller->$action_name($url_params);

// output appropriately
$view->render($data);

/public/rest/index.php

59

A Simple Controller

Now in UserController we add a GETAction
class UsersController {
public function GETAction($parameters) {
$users = array();
// imagine retreving data from models

if(isset($parameters[2])) {
return $users[(int)$parameters[2]];
} else {
return $users;
}
}
}

/public/rest/controllers.php

60

Calling our Service

Example uses curl, there are options

$ch = curl_init('http://api.local/rest/users');
$result = curl_exec($ch);
print_r(json_decode($result, true));

/public/rest-test.php

61

Extending our Service

Next we will add something to get the user’s friends
http://api.local/users/1/friends
class UsersController {
public function GETAction($parameters) {
$users = array();
$friends = array();
// imagine retreving data from models

if(isset($parameters[2])) {
if(isset($parameters[3]) && $parameters[3] == 'friends') {
return $friends[(int)$parameters[2]];
} else {
return $users[(int)$parameters[2]];
}
} else {
return $users;
}
}
}

62

Hypermedia

• The items returned are resources with their URLs

• This is hypermedia - providing links to related items/collections

• Allows a service to be self-documenting

• Allows a service to change its URLs - because they’re provided

63

Creating New Records

RESTful services use POST for creating data, so we have POSTAction

public function POSTAction($path, $data) {
// sanitise and validate data please!

// create a user from params
$new_user['name'] = isset($data['name']) ? $data['name'] : '';
$new_user['house'] = isset($data['house']) ? $data['house'] :
$new_user['age'] = isset($data['age']) ? $data['age'] : '';

// save the user, return the new id
$new_user['self'] = 'http://' . $_SERVER['HTTP_HOST'] . '/rest

// redirect user
header('HTTP/1.1 201 Created');
header('Location: http://api.local/rest/users/5');
return $new_user;
}


64

Incoming POST/PUT Data

We read from php://input which is a stream. So for JSON:

$verb = $_SERVER['REQUEST_METHOD'];
$data = array();
switch($verb) {
case 'GET':
parse_str($_SERVER['QUERY_STRING'], $data);
break;
case 'POST':
case 'PUT':
// incoming JSON data, it's an array
$data = json_decode(file_get_contents('php://input'), true);
break;

/public/rest/index.php

65

POSTing JSON Data from PHP

Adding some appropriate data handling and headers to the curl call:
$data = array("name" => "Hagrid", "age" => "36");
$data_string = json_encode($data);

$ch = curl_init('http://api.local/rest/users');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string))
);

$result = curl_exec($ch);

print_r(json_decode($result, true));

/public/rest-test.php

66

Appropriate Status Codes for REST

• GET

• 200 or maybe 302 if we found it somewhere else
• 404 if we can’t ﬁnd it

• POST

• 201 and a location header to the new resource
• or 400 if we can’t create an item

• PUT

• 204 for OK (but no content)
• 400 if the supplied data was invalid

• DELETE

• 200 at all times, for idempotency
67

Responding to Failure

• Use expected response format

• Collate all errors and return

• Help users help themselves

• Be consistent

• Be accurate

68

Technical Aspects

All PHP Best Practices apply equally to APIs

• Source control

• Unit/Integration testing

• Automated deployment

• Monitoring

Reliability and consistency are key

70

User Aspects

Who will use your API?

• Offer API Docs

• Write a quick start for the impatient

• Show examples, as many as possible

• Tutorials, blog posts, links to forum answers, anything

• Respond to questions

71

Resources

All links are in the bit.ly bundle bit.ly/emRpYT

73

Thanks

• http://joind.in/talk/view/3461

• http://lornajane.net

74

Web services tutorial

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Web services tutorial (20)

More from Lorna Mitchell (20)

Recently uploaded (20)

Web services tutorial