PHP Web Services, 2nd Edition

Chapter 12. Making Service Design Decisions

This is the million-dollar question: what kind of a service do I need for my next project? 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 these.

There’s rarely a clear-cut “one true way” when picking the best solution for a given API, but there are some key elements that can influence how to choose a solution that will be a good fit. 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?

There are some key points that are important to consider when planning an API that will help us answer these questions and deliver an effective API.

Consider the users’ needs

The API will be needed and utilized by users, not developers. Start out with a comprehensive set of user stories about how users intend to use the API, the kind of people that will be using it, and the technologies they are likely to want to use. Beginning from the point of view of what a user wants to achieve, rather than a developer’s preferred toolchain, is more likely to give a good API outcome.

Eat your own dogfood

The term “dogfood” is a bit of a strange one but it means to incorporate the tools you make and publish into your own workflows ...