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.

Answer 2

API 101

I am pasting this URL as a close approximation of the possible answer. Since I did not get any other answer, I think this is as close as it gets.

I will like to have more detail best practice outline, if someone find something better, let me know to mark their answer as accepted.

Answer 3

If you could answer some of these questions, you might get a more satisfactory answer.

1. who is the audience that will be consuming the the service?
2. What types of client technologies will be consuming the service
3. what assumptions/restrictions can you put on them (platforms, tooling, skill set)?
4. How broad is you API - how many methods will it expose?
5. Is security a consideration - how secure do you need to be?
6. Do you need to support transactions?