Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Web Services Tutorial
Web Services Tutorial

                 http://bit.ly/oaxVdy

      (while you’re waiting, download the files!)




       ...
About Me

 • Lorna Jane Mitchell

 • PHP Consultant/Developer

 • Author

 • API Specialist

 • Project Lead on http://joi...
The Plan

 • Talk about web services in general

 • Build a web service

 • Consume a web service

 • Talk about how to ma...
The Plan

 • Talk about web services in general

 • Build a web service

 • Consume a web service

 • Talk about how to ma...
Theory and Introduction
What Is A Web Service?

 • Means of exposing functionality or data

 • A lot like a web page, but for machines

 • Integra...
Integration Between Applications

Common to use an API internally as well as exposing it



            Website           ...
Separation Within an Application




                    Routing



    Auth      Images      Products   Orders




      ...
Separation Within an Application




                    Routing



    Auth      Images      Products   Orders




      ...
Web Services and You




             This is not rocket science

      You already know most of what you need!




      ...
Let’s Begin
Building Blocks

You can make an API from any tools you like

  • Existing MVC setup

  • Simple PHP (as in these examples...
My First Web Service

  • Make a virtual host

      • e.g. http://api.local
      • Don’t forget to restart apache
      ...
My First Web Service

  • Create the index.php file

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

$data = array(
    'form...
Consume Your Service

 • Use cURL from the command line

     • curl http://api.local

 • For more information about curl:...
JSON JavaScript Object Notation

   • Originally for JavaScript

   • Native read/write in most languages

   • Simple, li...
Heartbeat Method

 • A method which does nothing

 • No authentication

 • Requires correct request format

 • Gives basic...
Delivering A Web Service

  • Service

  • Documentation

  • Examples

  • A help point




                           18
HTTP and Data Formats
HTTP

HTTP is Hypertext Transfer Protocol. It is designed to exchange
information about a request/response.

  • Status Co...
Status Codes

Win or fail? Some common codes:

                     200   OK
                     204   No Content
       ...
Working with Status Codes in PHP

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

L...
HTTP Verbs

  • More than GET and POST

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

  • HEAD, OPTIONS an...
HTTP Headers

Headers are the metadata about the content we send/receive

Useful headers:

  • Accept and Content-Type: us...
Accept Header

What type of content can the consumer understand?

    • -v with curl to see request and response headers

...
Using the Accept Header

We can work out what format the user wanted to see from the Accept
header.
$data = array(
    'st...
How to REALLY Handle Accept Headers

Example accept header (from my browser)
text/html, application/xml;q=0.9, application...
Content-Type Header

The Content-Type header: literally labels the contents of the response.
We can include these in our e...
Handling XML Formats

We can work with XML in PHP almost as easily

  • Content type is text/xml or application/xml

  • T...
Adding XML to Our Service

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

$simplexml = simplexml_load_...
Versioning

  • Always include a version parameter or media type


http://example.com/api/v4/status

http://example.com/ap...
Data Formats

  • Handle multiple formats, by header or parameter

      • JSON
      • XML
      • ?

  • Common to detec...
Statelessness

 • Request alone contains all information needed

 • No data persistence between requests

 • Resource does...
Consuming Services from PHP
Consuming Your First Web Service

Three ways to consume web services:

  • Via streams (e.g. file_get_contents())

  • Usi...
Using File_Get_Contents

This is the simplest, especially for a GET request
$response = file_get_contents('http://api.loca...
Using Curl

This extension is commonly available
$ch = curl_init('http://api.local/');
curl_setopt($ch, CURLOPT_RETURNTRAN...
Using Pecl_HTTP

This is the most powerful and flexible, and can easily be installed from
http://pecl.php.net
$request = ne...
Service Types
Web Service Types

There are a few types of web service

  • RESTful

  • RPC (Remote Procedure Call)

       • XML-RPC
  ...
RPC Services

These services typically have:

   • A single endpoint

   • Method names

   • Method parameters

   • A re...
Soap

 • Not an acronym

       • (used to stand for Simple Object Access Protocol)

 • Special case of XML-RPC

 • VERY e...
Soap Example: Library Class

  public function eightBall() {
      $options = array(
          "Without a doubt",
        ...
Soap Server

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


include('Library.php');

$options = array('uri' => 'http://api.local/soa...
Consuming a Soap Service

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

$lib = new Library();
$response = $l...
Pros and Cons of Soap

 • Many languages have libraries for it

 • .NET and Java programmers in particular like it




   ...
Pros and Cons of Soap

 • Many languages have libraries for it

 • .NET and Java programmers in particular like it

 • Wei...
Pros and Cons of Soap

 • Many languages have libraries for it

 • .NET and Java programmers in particular like it

 • Wei...
Working with WSDLs

WSDL stands for Web Service Description Language

  • WSDLs were not designed for humans to read

  • ...
Debugging Soap

The Soap extension has some debug methods:

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

   ...
Extending Our Service
Consistency

 • Important to retain

     • Naming conventions
     • Parameter validation rules
     • Parameter order

 ...
The Action Parameter

As a simple place to start, let’s add an action parameter.
// route the request (filter input!)
$act...
Small APIs

 • Beware adding new functionality

 • Simple is maintainable

 • Easy to use and understand




             ...
Adding an Action

To add a new action, create a new method for the Actions class, returning
an array to pass to the output...
Access Control

A few common ways to identify users

  • Username and password with every request

  • Login action and gi...
RPC Service Example: Flickr

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

   • Supports multiple formats (for reque...
RPC vs REST

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

  • RPC services describe protoc...
RESTful Web Service
REST

  • REpresentational State Transfer

  • URLs are unique resource identifiers

  • HTTP verbs indicate which operatio...
REST as a Religion

Beware publishing a service labelled "RESTful"

  • Someone will always tell you it isn’t

  • They ar...
Making Our Service Restful

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

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

   • ht...
All Requests to index.php

We want to push all requests through index.php, there is an .htaccess file
that does this
<IfMod...
Routing Within Our App

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

Now in UserController we add a GETAction
class UsersController {
    public function GETAction($param...
Extending our Service

Next we will add something to get the user’s friends
http://api.local/users/1/friends
class UsersCo...
Hypermedia

 • The items returned are resources with their URLs

 • This is hypermedia - providing links to related items/...
Creating New Records

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

curl -X POST http://api.local/us...
Updating Records

  • To create: we used POST

  • To update: we use PUT

The code looks basically the same, apart from:
/...
Appropriate Status Codes for REST

 • GET

    • 200 or maybe 302 if we found it somewhere else
    • 404 if we can’t find ...
Responding to Failure

  • Use expected response format

  • Collate all errors and return

  • Help users help themselves...
Delivering Services
Technical Aspects

All PHP Best Practices apply equally to APIs

   • Source control

   • Unit/Integration testing

   • ...
User Aspects

Who will use your API?

  • Offer API Docs

  • Write a quick start for the impatient

  • Show examples, as...
Questions?
Resources

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




                                                   74
Thanks




         https://joind.in/6217

              @lornajane

         http://lornajane.net




                   ...
Upcoming SlideShare
Loading in …5
×

of

Web Services PHP Tutorial Slide 1 Web Services PHP Tutorial Slide 2 Web Services PHP Tutorial Slide 3 Web Services PHP Tutorial Slide 4 Web Services PHP Tutorial Slide 5 Web Services PHP Tutorial Slide 6 Web Services PHP Tutorial Slide 7 Web Services PHP Tutorial Slide 8 Web Services PHP Tutorial Slide 9 Web Services PHP Tutorial Slide 10 Web Services PHP Tutorial Slide 11 Web Services PHP Tutorial Slide 12 Web Services PHP Tutorial Slide 13 Web Services PHP Tutorial Slide 14 Web Services PHP Tutorial Slide 15 Web Services PHP Tutorial Slide 16 Web Services PHP Tutorial Slide 17 Web Services PHP Tutorial Slide 18 Web Services PHP Tutorial Slide 19 Web Services PHP Tutorial Slide 20 Web Services PHP Tutorial Slide 21 Web Services PHP Tutorial Slide 22 Web Services PHP Tutorial Slide 23 Web Services PHP Tutorial Slide 24 Web Services PHP Tutorial Slide 25 Web Services PHP Tutorial Slide 26 Web Services PHP Tutorial Slide 27 Web Services PHP Tutorial Slide 28 Web Services PHP Tutorial Slide 29 Web Services PHP Tutorial Slide 30 Web Services PHP Tutorial Slide 31 Web Services PHP Tutorial Slide 32 Web Services PHP Tutorial Slide 33 Web Services PHP Tutorial Slide 34 Web Services PHP Tutorial Slide 35 Web Services PHP Tutorial Slide 36 Web Services PHP Tutorial Slide 37 Web Services PHP Tutorial Slide 38 Web Services PHP Tutorial Slide 39 Web Services PHP Tutorial Slide 40 Web Services PHP Tutorial Slide 41 Web Services PHP Tutorial Slide 42 Web Services PHP Tutorial Slide 43 Web Services PHP Tutorial Slide 44 Web Services PHP Tutorial Slide 45 Web Services PHP Tutorial Slide 46 Web Services PHP Tutorial Slide 47 Web Services PHP Tutorial Slide 48 Web Services PHP Tutorial Slide 49 Web Services PHP Tutorial Slide 50 Web Services PHP Tutorial Slide 51 Web Services PHP Tutorial Slide 52 Web Services PHP Tutorial Slide 53 Web Services PHP Tutorial Slide 54 Web Services PHP Tutorial Slide 55 Web Services PHP Tutorial Slide 56 Web Services PHP Tutorial Slide 57 Web Services PHP Tutorial Slide 58 Web Services PHP Tutorial Slide 59 Web Services PHP Tutorial Slide 60 Web Services PHP Tutorial Slide 61 Web Services PHP Tutorial Slide 62 Web Services PHP Tutorial Slide 63 Web Services PHP Tutorial Slide 64 Web Services PHP Tutorial Slide 65 Web Services PHP Tutorial Slide 66 Web Services PHP Tutorial Slide 67 Web Services PHP Tutorial Slide 68 Web Services PHP Tutorial Slide 69 Web Services PHP Tutorial Slide 70 Web Services PHP Tutorial Slide 71 Web Services PHP Tutorial Slide 72 Web Services PHP Tutorial Slide 73 Web Services PHP Tutorial Slide 74 Web Services PHP Tutorial Slide 75 Web Services PHP Tutorial Slide 76 Web Services PHP Tutorial Slide 77 Web Services PHP Tutorial Slide 78
Upcoming SlideShare
Advanced Web Services Hacking (AusCERT 06)
Next
Download to read offline and view in fullscreen.

102 Likes

Share

Download to read offline

Web Services PHP Tutorial

Download to read offline

Web services tutorial slides from my session at DPC 2012 in Amsterdam. In this 3-hour session we built the simplest possible service, and then extended it, looking at RPC, REST and SOAP along the way.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

Web Services PHP Tutorial

  1. 1. Web Services Tutorial
  2. 2. Web Services Tutorial http://bit.ly/oaxVdy (while you’re waiting, download the files!) 2
  3. 3. About Me • Lorna Jane Mitchell • PHP Consultant/Developer • Author • API Specialist • Project Lead on http://joind.in • Twitter: @lornajane • Website: http://lornajane.net 3
  4. 4. The Plan • Talk about web services in general • Build a web service • Consume a web service • Talk about how to make excellent web services 4
  5. 5. The Plan • Talk about web services in general • Build a web service • Consume a web service • Talk about how to make excellent web services • (we’ll hide some actual textbook theory in there somewhere) • Ask questions! 4
  6. 6. Theory and Introduction
  7. 7. What Is A Web Service? • Means of exposing functionality or data • A lot like a web page, but for machines • Integration between applications • Separation within an application 6
  8. 8. Integration Between Applications Common to use an API internally as well as exposing it Website 3rd Party / Apps API Data Store 7
  9. 9. Separation Within an Application Routing Auth Images Products Orders 8
  10. 10. Separation Within an Application Routing Auth Images Products Orders 9
  11. 11. Web Services and You This is not rocket science You already know most of what you need! 10
  12. 12. Let’s Begin
  13. 13. Building Blocks You can make an API from any tools you like • Existing MVC setup • Simple PHP (as in these examples) • Framework modules • Component library 12
  14. 14. 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 file <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 13
  15. 15. My First Web Service • Create the index.php file • e.g. /var/www/myapi/public/index.php $data = array( 'format' => 'json', 'status' => 'live' ); echo json_encode($data); public/index.php 14
  16. 16. Consume Your Service • Use cURL from the command line • curl http://api.local • For more information about curl: • http://curl.haxx.se/ - curl homepage • http://bit.ly/esqBmz - my cheat sheet 15
  17. 17. 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'} 16
  18. 18. Heartbeat Method • A method which does nothing • No authentication • Requires correct request format • Gives basic feedback • Shows that service is alive 17
  19. 19. Delivering A Web Service • Service • Documentation • Examples • A help point 18
  20. 20. HTTP and Data Formats
  21. 21. HTTP HTTP is Hypertext Transfer Protocol. It is designed to exchange information about a request/response. • Status Codes (e.g. 200, 404) • Headers (e.g. Content-Type, Authorization) • Verbs (e.g GET, POST) 20
  22. 22. Status Codes Win or fail? Some common codes: 200 OK 204 No Content 302 Found 301 Moved Permanently 302 Found 400 Bad Request 401 Not Authorised 403 Forbidden 404 Not Found 500 Internal Server Error For more, see: http://bitly.com/h03Dxe 21
  23. 23. 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' ); echo json_encode($data); 22
  24. 24. HTTP Verbs • More than GET and POST • PUT and DELETE to update and delete in a RESTful service • HEAD, OPTIONS and others also specified GET Read POST Create In REST, we use: PUT Update DELETE Delete 23
  25. 25. 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 24
  26. 26. 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 > 25
  27. 27. 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 echo json_encode($data); } public/headers.php 26
  28. 28. 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
  29. 29. 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'); echo json_encode($data); } public/headers.php 28
  30. 30. 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: HTML, XML, JSON ... 29
  31. 31. 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(); public/headers.php The result is this: <?xml version="1.0"?> <data><status>live</status><now>1302981884</now></data> 30
  32. 32. Versioning • Always include a version parameter or media type http://example.com/api/v4/status http://example.com/api/status Content-Type: application/vnd.myapi.2+json 31
  33. 33. Data Formats • Handle multiple formats, by header or parameter • JSON • XML • ? • Common to detect header, allow parameter override http://example.com/api/v4/status Accept: application/json http://example.com/api/v4/status?format=json Accept: text/html 32
  34. 34. 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 33
  35. 35. Consuming Services from PHP
  36. 36. Consuming Your First Web Service Three ways to consume web services: • Via streams (e.g. file_get_contents()) • Using the curl extension • http://lrnja.net/I5JD9R • Using Pecl_HTTP • http://lrnja.net/I23yZj 35
  37. 37. Using File_Get_Contents This is the simplest, especially for a GET request $response = file_get_contents('http://api.local/'); var_dump($response); You can set more information in the stream context bit.ly/gxBAgV 36
  38. 38. Using Curl This extension is commonly available $ch = curl_init('http://api.local/'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); var_dump($response); Look out for the CURLOPT_RETURNTRANSFER; without it, this will echo the output 37
  39. 39. Using Pecl_HTTP This is the most powerful and flexible, and can easily be installed from http://pecl.php.net $request = new HTTPRequest('http://api.local/', HTTP_METH_GET); $request->send(); $response = $request->getResponseBody(); var_dump($response); Strongly recommend pecl_http if you are able to install pecl modules on your platform 38
  40. 40. Service Types
  41. 41. Web Service Types There are a few types of web service • RESTful • RPC (Remote Procedure Call) • XML-RPC • JSON-RPC • Soap 40
  42. 42. RPC Services These services typically have: • A single endpoint • Method names • Method parameters • A return value • Often all POST requests A familiar model for us as developers 41
  43. 43. 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 42
  44. 44. Soap Example: Library Class public function eightBall() { $options = array( "Without a doubt", "As I see it, yes", "Most likely", "Reply hazy, try again", "Better not tell you now", "Concentrate and ask again", "Don't count on it", "Very doubtful"); return $options[array_rand($options)]; } /public/soap/Library.php 43
  45. 45. Soap Server (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 44
  46. 46. Consuming a Soap Service To call PHP directly, we would do: include('Library.php'); $lib = new Library(); $response = $lib->eightBall(); echo $response; Over Soap: $options = array('uri' => 'http://myapi.local', 'location' => 'http://myapi.local/soap/'); try{ $client = new SoapClient(NULL, $options); $response = $client->eightBall(); echo $response; } catch (SoapFault $e) { echo "ERROR: " . $e->getMessage(); } 45
  47. 47. Pros and Cons of Soap • Many languages have libraries for it • .NET and Java programmers in particular like it 46
  48. 48. Pros and Cons of Soap • Many languages have libraries for it • .NET and Java programmers in particular like it • Weird things happen between languages regarding data types • When it works, it’s marvellous • When it doesn’t work, it’s horrid to debug (so I’ll show you how) 46
  49. 49. Pros and Cons of Soap • Many languages have libraries for it • .NET and Java programmers in particular like it • Weird things happen between languages regarding data types • 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! 46
  50. 50. 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 47
  51. 51. 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) 48
  52. 52. Extending Our Service
  53. 53. Consistency • Important to retain • Naming conventions • Parameter validation rules • Parameter order • Just as you would in library code 50
  54. 54. 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 51
  55. 55. Small APIs • Beware adding new functionality • Simple is maintainable • Easy to use and understand 52
  56. 56. 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 // route the request (filter input!) $action = $_GET['action']; $library = new Actions(); // OBVIOUSLY you would filter input at this point $data = $library->$action($_GET); /rpc/index.php 53
  57. 57. 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, firewalls 54
  58. 58. 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 flickr functionality elsewhere 55
  59. 59. 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 56
  60. 60. RESTful Web Service
  61. 61. REST • REpresentational State Transfer • URLs are unique resource identifiers • 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/ 58
  62. 62. 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 fit badly around business requirements • Flamewars will ensue Instead: "An HTTP Web Service" 59
  63. 63. 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 specific item is a resource; where you request a list, e.g. /user, this is called a collection 60
  64. 64. All Requests to index.php We want to push all requests through index.php, there is an .htaccess file 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 61
  65. 65. 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() // route the request (filter input!) $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 62
  66. 66. 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 63
  67. 67. 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; } } } /public/rest/controllers.php 64
  68. 68. 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 65
  69. 69. Creating New Records RESTful services use POST for creating data, so we have POSTAction curl -X POST http://api.local/users -d name="Fred Weasley" public function POSTAction() { // sanitise and validate data please! $data = $_POST; // create a user from params $user['name'] = $data['name']; // save the user, return the new id // redirect user header('201 Created', true, 201); header('Location: http://api.local/rest/users/5'); return $user; } /public/rest/controllers.php 66
  70. 70. Updating Records • To create: we used POST • To update: we use PUT The code looks basically the same, apart from: // instead of this: $data = $_POST; // use this: parse_str(file_get_contents('php://input'), $data); 67
  71. 71. Appropriate Status Codes for REST • GET • 200 or maybe 302 if we found it somewhere else • 404 if we can’t find 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 68
  72. 72. Responding to Failure • Use expected response format • Collate all errors and return • Help users help themselves • Be consistent • Be accurate 69
  73. 73. Delivering Services
  74. 74. Technical Aspects All PHP Best Practices apply equally to APIs • Source control • Unit/Integration testing • Automated deployment • Monitoring Reliability and consistency are key 71
  75. 75. 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 72
  76. 76. Questions?
  77. 77. Resources All links are in the bit.ly bundle bit.ly/emRpYT 74
  78. 78. Thanks https://joind.in/6217 @lornajane http://lornajane.net 75
  • shiranishirani1

    Dec. 31, 2020
  • samchanpanha

    Jul. 8, 2020
  • MarionaBatallaTaylor

    Jan. 29, 2020
  • greietes

    Jan. 5, 2020
  • POEDARLITHEINT

    Oct. 31, 2019
  • sinakhabbazhaghighi

    Apr. 12, 2019
  • MDALAM65

    Jan. 24, 2019
  • JuanCarlosHidalgo2

    Mar. 15, 2018
  • satyasvv2

    Nov. 27, 2017
  • AkhileshVyawahare

    Jun. 8, 2017
  • hilalhk5

    Mar. 4, 2017
  • ClaAurianneLeencBAWE

    Jan. 9, 2017
  • teerapuch

    Nov. 5, 2016
  • BikashKhatri1

    Oct. 31, 2016
  • RajeshKumar909

    Oct. 11, 2016
  • baagii1988

    Oct. 11, 2016
  • umairkhan178

    Sep. 25, 2016
  • ShabbirAlam11

    Sep. 21, 2016
  • antoniofaccioli

    Aug. 20, 2016
  • JamaalIsmaaciil

    Aug. 3, 2016

Web services tutorial slides from my session at DPC 2012 in Amsterdam. In this 3-hour session we built the simplest possible service, and then extended it, looking at RPC, REST and SOAP along the way.

Views

Total views

223,596

On Slideshare

0

From embeds

0

Number of embeds

4,106

Actions

Downloads

4,213

Shares

0

Comments

0

Likes

102

×