What are some of the pitfalls/tips one could give for developing a web service

Question

Looking to develop a web service (api) in PHP to offer customers an easier way to integrate with our platform. There are workflow calls that will be validated with user/pass as well as some reporting options.

Sorry I can't post more details or code on the subject and I have never developed a web service but have had experience in using them via SOAP.

Now I would also need to offer a state or status of the workflow and I think REST would be the best choice here, but still looking for opinions on that.

For reporting I would like to offer different options such as XML,Excel/CSV any reason I would pick one over the other?

What are some of the pitfalls I should lookout for?

What are some gems anyone could offer.

Thanks in advance to any help as this is very important for me to understand.

UPDATE #1:

• What would be the most secure method?
• What is the most flexible method (Platform independent)

UPDATE #2: a little bit about the data flow. Each user has creds to use the API and no data is shared between users. Usage is submit a request, the request is processed and a return is given. no updates. (Think Google) a search request is made and results are given, but in my case only one result is given. Don't know if this is needed so it's an FYI.

Answer 1

Always handle errors and exceptions.

Problems will always make their presence felt in the application/api. Either at start or through further development. Don't leave this as an end task, and make it clear when an error occurs, with well documented response messages.

Also if your service will handle many requests, and for the same resource id (independent from user) the same resource is returned be sure to cache the information. And this not only for performance reasons, but for the cases when errors stuck up. This ways you can at least serve something to the client (possibly useful, more context required to be explicit).

Answer 2

The biggest and most important item I can offer is to guarantee your infrastructure behind the WS or at least what you are serving up via the WS is stateless. The moment you deviate form this it will become a nightmare and you will begin having to shoehorn code in to protect your data from getting fouled up.

An example would be a two clients making changes to data via the WS, ie...save configuration. How you deal with that on the back end makes things interesting. If your data is only heading outbound, you are in a much better situation then if you have to support pushing data into the back end.

Also, think out the API's in depth as with any public facing API. The moment you have a version out in the wild and then decide that API needs changed or deprecated begins to cause problems for the client base making use of your WS.