Yesterday, I saw this tweet:
I have lots of advice for Olly (whom I know personally) but there's no way it will fit into a tweet! So here it is, in rather longer form :)
Whatever data format you pick, whatever app you are building, whichever approach you choose, be consistent. Your whole API should call things by the same name, use the same validation rules for everything, and accept parameters in the same order. Every time. Look out in particular for things like singular/plural names, mixing case and parameters which are sometimes optional.
Fail Really Really Excellently
Things will go wrong. This is the way the world works in general, and on the web in particular. Requests sometimes don't arrive, or the responses don't. Disks fill up, databases fall offline, all kinds of weird stuff does happen. All that matters is how you deal with it.
Make all your errors arrive in the same format as the successful response would have. This means that the client can parse it and understand what is there. If you feed HTML into something that wasn't expecting it, something unexpected will happen (actually PHP's
json_decode() will cause PHP to segfault if you try hard enough).
Give meaningful error messages. This allows users to help themselves, continue to use your API, hopefully learn to love it - and all without having to bother you in the process. This is the holy grail of API creation!
Keep It Tidy
A Small API is easy to maintain and support, so try to keep your APIs as minimal as possible. Only write functionality that is really needed. Make things flexible so that clients can ask for more or fewer records than the default (especially if the data sets can get large!), and get the result set sorted sensibly - it's very expensive to do those kinds of operations on any kind of large data set on a small device.
Keeping this small is also keeping things simple, and the KISS principle is good advice for all areas of software design.
The Actual Advice
For a non-novice programmer, an API is a project that is absolutely approachable. For sending data to a smart phone, I'd recommend the following:
- JSON format - it's lightweight, easy to parse, and also relatively easy to debug if you need to
- RPC style - REST is much cooler, but it's hard to get started with if you haven't used it before, and bad REST just gets everyone upset. You already know how to declare and call a function - so make your API along those lines. Look at wikipedia's JSON-RPC page for some ideas
- Make sure you understand HTTP headers and status codes, and use them! Use Accept and Content-Type for sorting out data formats, status codes to say if things went well or not.
- I feel like there should be more advice here ... please add a comment if you know what else I should be telling Olly!
Tools to Help You
You'll be doing a lot of debugging,
print_r($_SERVER) is a good place to start with understanding what requests came in. Use wireshark to make sure that you are sending and receiving what you think you are send and receiving. If you need to debug output but doing so breaks your client because it sends nonsense in the data format, use
Most of all, know this: if you can already build a website, you can build an API. Good luck :)