Is there web service (API) standard or best practice for developer teams?

Question

If you are going to start the development of an API for your web application. Is there any kind of guidelines, best practices or standard to build web services. I have seen a few discussions in this topic and I will like to get more information.

At least get pointers on where to get the information.

Thanks in advance.

Answer 1

There exists a wide variety and latitude regarding "web services". I find it useful to make explicit note of what we are talking about:

web = transported over HTTP(S)
service = remote procedure call (RPC)

Note that the HTTP(S) portion of this merely specifies the transport medium, but not the content. Also note that the RPC portion of this merely specifies the behavior (essentially invoking remotely a named function with arguments that returns a result) but not the content.

A critical question that arises is whether you control both sides of the communication. If so, but especially if not, you need to be concerned about interoperability.

SOAP is a standard for implementing a web service that specifies using specificly-formatted XML for the content of the request and response. It is VERY heavy, and there are still problems with interoperability across various implementations.

There are lots of custom implementations, most of which are lighter, but you will almost certainly have interoperability issues.

Since any form of content can potentially be used to achieve a web service, I recommend picking something that is able to handle complex content (to varying degrees), standardized, lightweight, and robust.

I am recently leaning towards JSON for the content format. I recommend considering the same, especially if you are considering implementing AJAX.

Best wishes.