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 12. Making Service Design Decisions

This is the million dollar question: what kind of a service are you going to build? REST is cool, but RPC is familiar. JSON is lighter, but the client already works with XML. The API will be used by mobile consumers, or web consumers, or a reporting engine, or all of the above.

There’s rarely a clear-cut “one true way” to pick the right solution for the API but there are some key elements which will influence how you choose a solution that will work for you. API design is mostly engineering with a generous dash of common sense also required.

The big questions you need to ask at each step are these:

  1. Who will be using this API?
  2. What are they trying to achieve?
  3. Which technologies do they use?

With these in mind, you can consider each of the points below. It can be helpful to create some user stories to represent some of the expected users and tasks that your API will serve. Building APIs is all about creating an interface point which makes sense when viewed from the outside, so your users’ perspective is always the lens needed to scrutinise any decision. Not every piece of data or possible piece of functionality in your application will necessarily make sense exposed over an API, so don’t be tempted to build something huge immediately!

Service Type Decisions

The first decision you make when designing any API is one that can’t be changed; you will first decide what kind of a service you will offer. This depends on a combination of your audience ...

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