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 15. Documentation

Raise your hand if you like writing documentation. Now raise your hand if you like discovering that the API you are to integrate against is well-documented and has examples of applications similar to what you need it for. These two are in direct conflict since very often, developers don’t enjoy writing documentation, and while they often don’t read it either, good documentation will ease the path of developers into using your service rather than either logging a support ticket, or just going away and using you competitors’ offerings.

Your API might be the best the world has ever seen, but without any supporting documentation, or with bad/inaccurate documentation, people won’t be able to use it. In fact, without considering great documentation as part of your project, one could argue that you may as well save yourself even more time and not build the API either!

There are many types of documentation, and a great web service probably needs a bit of all of them. In the following sections we’ll look at the various kinds of documentation that are useful to accompany a web service and give some suggestions of tools you can use to generate and maintain these.

Overview Documentation

This is the welcoming committee of your API, gets people over the threshold and gives them confidence that they are about to have a good time. The overview documentation will set the tone of the API and provide some pointers for where to find the more detailed information. In general, it ...

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