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

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.

Answer 2

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 3

I am currently working on a web application that includes a web service (or 2 in ASP.NET MVC) and I highly recommend looking at the principles behind Service Oriented Architecture (SOA) as what I have found is that the most important aspect is to get the design of the web service API correct as that will effect the rest of your back end and either make your life easier or have you running into walls out of frustration.

Essentially SOA means design the web service around business processes, i.e. how the people who use your API are likely to use it.

A Good desgin is always a good idea, so I highly recommend you do a lot of reading on Web Sevice Design Principles before you start coding and save yourself or some other unlucky sod alot of grief latter on.

Also make sure that your design is agile as it will change frequently as communication between your company and your clients happens.

Answer 4

A little bit more related to implementation than design: I would decide that the output of the service to be XML - this can be very easy parsed, by all decent languages. Also, if some client need other output, you could transform those XMLs through some XSLT processors and offer "other" web services, that outputs JSON, or whatever else they need. Regarding the reporting, that depends on how the reports will be used - if the clients process them and they need only the data from the reports - then again suggest XML. In my opinion working with CSV is harder because you have to take in consideration all kind of special cases like "what happen if my data contains the separator field", "will the client be able to specify the separator", "how will I represent nested data", or all of these are straight forward with XML. If your client needs reports to use them out of the box you could use BIRT -beautiful and free

Answer 5

Offering multiple outputs like JSON, CSV, YAML or XML is good - that gives the end user confort, at a very small cost! Dumping data is always easier than processing, and say that they already parse JSON for some reason - it is much easier to just hook that up for your API than implementing, say an XML-parser. Nowadays I see XML-parsers everywhere, so that should probably not be a problem, but I like the more "air-ish" nature of JSON; I have looked a little into YAML but never used it - but it looks promising, I'll definitively use that for the config files of my next project.

On the security side of anything that dynamically processes any input an user gives, one should treat such input like something you would not poke on even with a stick.

IMHO stateless REST is better than SOAP because it is less overhead, one can easily communicate with a REST-api by hand using curl or wget from the terminal. Jump-start so to say.

I would reccomend you to take a deep breath, a pencil & a paper, sit and sketch down everything that is going to be needed. Then you remove the less important stuff, and take a new paper and start to organize it. You can add the less important stuff in the next version of the API.

Try to design the API so that you don't lock yourself into a corner, make no assumptions on where it is going to head next.