You are previewing PHP Web Services.

PHP Web Services

Cover of PHP Web Services by Lorna Jane Mitchell Published by O'Reilly Media, Inc.
  1. Preface
    1. Conventions Used in This Book
    2. Using Code Examples
    3. Safari® Books Online
    4. How to Contact Us
  2. 1. Introduction
  3. 2. HTTP
    1. Examining HTTP
      1. Curl
      2. Browser Tools
      3. PHP
  4. 3. Request and Response
    1. Clients and Servers
  5. 4. HTTP Verbs
    1. GET
    2. POST
    3. Other HTTP Verbs
  6. 5. Headers
    1. Request and Response Headers
    2. Common HTTP Headers
      1. User-Agent
      2. Headers for Content Negotiation
      3. Authorization
      4. Custom Headers
  7. 6. Cookies
    1. Cookie Mechanics
    2. Working With Cookies in PHP
  8. 7. JSON
    1. When to Choose JSON
    2. Handling JSON with PHP
    3. JSON in Existing APIs
  9. 8. XML
    1. When To Choose XML
    2. XML in PHP
    3. XML in Existing APIs
  10. 9. RPC and SOAP Services
    1. RPC
    2. SOAP
      1. WSDL
      2. PHP SOAP Client
      3. PHP SOAP Server
      4. Generating a WSDL File from PHP
      5. PHP Client and Server with WSDL
  11. 10. REST
    1. RESTful URLs
    2. Resource Structure and Hypermedia
    3. Data and Media Types
    4. HTTP Features in REST
      1. Create Resources
      2. Read Records
      3. Update Records
      4. Delete Records
    5. Additional Headers in RESTful Services
      1. Authorisation Headers
      2. Caching Headers
    6. RESTful vs Useful
  12. 11. Debugging Web Services
    1. Debug Output
    2. Logging
    3. Debugging From Outside Your Application
      1. Wireshark
      2. Charles Proxy
    4. Finding the Tool for the Job
  13. 12. Making Service Design Decisions
    1. Service Type Decisions
    2. Consider Data Formats
    3. Customisable Experiences
    4. Pick Your Defaults
  14. 13. Building a Robust Service
    1. Consistency is Key
      1. Consistent and Meaningful Naming
      2. Common Validation Rules
      3. Predictable Structures
    2. Making Design Decisions for Robustness
  15. 14. Error Handling in APIs
    1. Output Format
    2. Meaningful Error Messages
    3. What To Do When You See Errors
  16. 15. Documentation
    1. Overview Documentation
    2. API Documentation
    3. Interactive Documentation
    4. Tutorials and the Wider Ecosystem
  17. A. A Guide To Common Status Codes
  18. B. Common HTTP Headers
  19. About the Author
  20. Copyright
O'Reilly logo

Chapter 14. Error Handling in APIs

Errors are a fact of life. Users will enter nonsense into your system, not because they are idiots (although it does often look that way), but because their expectations and understanding is different to yours. The internet is a very loosely-coupled affair and all kinds of things can and will go wrong at a technical level, once in a while. How your API handles these inevitable situations is a measure of the quality and design of your API, so this chapter gives some pointers on what to look out for and how to do it well.

Output Format

This is the golden rule: always respond in the format that the client was expecting. This means that it is never acceptable to return an HTML error message when the client expected JSON (in fact, in certain PHP versions, passing invalid JSON to json_decode() causes a segfault!). If your system does return HTML messages when things go wrong, that is a bug and needs fixing. If we send an unexpected format, the client may not be unable to understand the response and any error information contained in it.

In order to be able to handle this requirement, we can follow some established patterns when designing our API that may help. Many modern applications have some kind of “front controller” pattern, where all incoming requests are handled by a common entry point. This common front controller typically parses the request and figures out which part of the system it should be passed on to. We can put the same ideas into practice ...

The best content for your career. Discover unlimited learning on demand for around $1/day.