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:
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!
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 ...