PHP Web Services: APIs for the Modern Web

180 Pages·2016·10.8 MB·English

by  Lorna Jane Mitchell

SECOND EDITION
PHP Web Services
Lorna Jane Mitchell
Boston
PHP Web Services
by Lorna Jane Mitchell
Copyright © 2016 Lorna Mitchell. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are
also available for most titles (http://safaribooksonline.com). For more information, contact our corporate/
institutional sales department: 800-998-9938 or [email protected].
Editor: Allyson MacDonald Indexer: WordCo Indexing Services
Production Editor: Colleen Lobner Interior Designer: David Futato
Copyeditor: Charles Roumeliotis Cover Designer: Randy Comer
Proofreader: James Fraleigh Illustrator: Rebecca Demarest
April 2013: First Edition
January 2016: Second Edition
Revision History for the Second Edition
2016-01-05: First Release
See http://oreilly.com/catalog/errata.csp?isbn=9781491933091 for release details.
The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. PHP Web Services, the cover image of
an alpine accentor, and related trade dress are trademarks of O’Reilly Media, Inc.
While the publisher and the author have used good faith efforts to ensure that the information and
instructions contained in this work are accurate, the publisher and the author disclaim all responsibility
for errors or omissions, including without limitation responsibility for damages resulting from the use of
or reliance on this work. Use of the information and instructions contained in this work is at your own
risk. If any code samples or other technology this work contains or describes is subject to open source
licenses or the intellectual property rights of others, it is your responsibility to ensure that your use
thereof complies with such licenses and/or rights.
978-1-491-93309-1
[LSI]
Table of Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
1. HTTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Clients and Servers 4
Making HTTP Requests 5
Command-Line HTTP 6
Browser Tools 10
Doing HTTP with PHP 12
2. HTTP Verbs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Serving GET Requests 17
Making GET Requests 19
Handling POST Requests 20
Making POST Requests 22
Using Other HTTP Verbs 23
3. Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Request and Response Headers 28
Identify Clients with User-Agent 29
Headers for Content Negotiation 30
Parsing an Accept Header 31
Demonstrating Accept Headers with cURL 33
Securing Requests with the Authorization Header 34
HTTP Basic Authentication 35
HTTP Digest Authentication 36
OAuth 36
Caching Headers 37
Custom Headers 38
iii
4. Cookies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Cookie Mechanics 41
Reading and Writing Cookies 43
Making Requests with Cookies 44
Cookies and APIs 45
5. JSON. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
When to Choose JSON 48
Handling JSON with PHP 49
The JSONSerializable Interface 50
Consuming JSON APIs 51
6. XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
XML in PHP 55
Creating XML 55
Consuming XML APIs 58
Parsing XML 58
Flickr’s XML API 58
7. RPC and SOAP Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
RPC 63
SOAP 66
WSDL 66
PHP SOAP Client 67
PHP SOAP Server 68
Generating a WSDL File from PHP 70
PHP Client and Server with WSDL 72
8. REST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
RESTful URLs 76
Resource Structure and Hypermedia 76
Build the Basic RESTful Server 79
Example Project: The Wishlist 79
Create Resources with POST 82
Fetch a Resource or Collection with GET 84
Update a Resource with PUT 87
DELETE a Resource 88
RESTful Versus Useful 90
9. Webhooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
GitHub’s Webhooks 92
Publishing Your Own Webhooks 94
iv | Table of Contents
10. HTTP Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Easy Command-Line JSON 98
Graphical cURL Alternatives 100
Inspect HTTP Traffic with Wireshark 101
Tunnel Local Traffic Remotely with ngrok 105
Inspect, Edit, Repeat, and Share Requests 107
Proxying PHP Applications 111
Proxy Settings for Guzzle 111
Proxy Settings for HTTP Stream Handling 112
Finding the Tool for the Job 112
11. Maintainable Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Sample API Application 113
Consistent Output Formats 115
Debug Output as a Tool 117
Effective Logging Techniques 120
Error Logging in PHP Applications with Monolog 122
Error Handling with PHP Exceptions 123
12. Making Service Design Decisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Service Type Decisions 128
How to Present API Data 129
Hypermedia for Easy API Navigation 130
Nested Data or Many Round Trips 130
Data Formats and Media Types 131
Customizable Experiences 134
Pick Your Defaults 137
13. Building a Robust Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Consistency Is Key 139
Consistent and Meaningful Naming 140
Common Validation Rules 140
Predictable Structures 141
Error Handling in APIs 142
Meaningful Error Messages 142
What to Do When You See Errors 143
Making Design Decisions for Robustness 144
14. Publishing Your API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Documentation Is Key 145
Overview Documentation 145
Generated API Documentation 146
Table of Contents | v
Interactive Documentation 148
API Description Languages 150
Automated Testing Tools 151
Tutorials and the Wider Ecosystem 154
A. A Guide to Common Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
B. Common HTTP Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
vi | Table of Contents
Preface
In this age, when it can sometimes seem like every system is connected to every other
system, dealing with data has become a major ingredient in building the Web.
Whether you will be delivering services or consuming them, web service is a key part
of all modern, public-facing applications, and this book is here to help you navigate
your way along the road ahead. We will cover the different styles of service—from
RPC, to SOAP, to REST—and you will see how to devise great solutions using these
existing approaches, as well as examples of APIs in the wild. Whether you’re sharing
data between two internal systems, using a service backend for a mobile application,
or just plain building an API so that users can access their data, this book has you
covered, from the technical sections on HTTP, JSON, and XML to the “big picture”
areas such as creating a robust service.
Why did we pick PHP for this book? Well, PHP has always taken on the mission to
“solve the web problem.” Web services are very much part of that “problem” and PHP
is ideally equipped to make your life easy, both when consuming external services
and when creating your own. As a language, it runs on many platforms and is the
technology behind more than half of the Web, so you can be sure that it will be widely
available, wherever you are.
The book walks you through everything you need to know in three broad sections.
We begin by covering HTTP and the theory that goes with it, including detailed
chapters on the request/response cycle, HTTP verbs and headers, and cookies. There
are also chapters on JSON and XML: when to choose each data format, and how to
handle them from within PHP. The second section aims to give very practical advice
on working with RPC and SOAP services and with RESTful services, and on how to
debug almost anything that works over HTTP, using a variety of tools and techniques.
In the final section, we look at some of the wider issues surrounding the design of
top-quality services, choosing what kind of service will work for your application,
and determining how to make it robust. Another chapter is dedicated to handling
errors and giving advice on why and how to document your API. Whether you dip
into the book as a reference for a specific project, or read it in order to find out more
vii
about this area of technology, there’s something here to help you and your project
find success. Enjoy!
Conventions Used in This Book
The following typographical conventions are used in this book:
Italic
Indicates new terms, URLs, email addresses, filenames, and file extensions.
Constant width
Used for program listings, as well as within paragraphs to refer to program ele‐
ments such as variable or function names, databases, data types, environment
variables, statements, and keywords.
Constant width bold
Shows commands or other text that should be typed literally by the user.
Constant width italic
Shows text that should be replaced with user-supplied values or by values deter‐
mined by context.
This element signifies a tip or suggestion.
This element signifies a general note.
This element indicates a warning or caution.
viii | Preface