How to write a JavaScript API? [closed]

Question

I am looking to create an API so other sites can access data from my web application.

I haven't been able to find any resources online that explain the process of creating your own javascript API.

I want to learn how to setup authentication, data transmission, etc.

How do I write my own JavaScript API?

Are there any good tutorials that explain the process of creating a JavaScript API like the GData API or YouTube API?

I will actually be doing this on 2 different apps. One is on an apache server with Tomcat, MySQL, and Java. The other is on apache with MySQL and PHP. The front-end is all written in javascript through which it interfaces with the backend. I have already begun writing the library they will use to interact with our functions.

Answer 1

This is a very generic/broad question, and as such will only garner very generic/broad responses. It is difficult to make any recommendations without knowing what server side technologies you are using, how you are currently architected, how much work is done compared to how much has to be done (relevant for how much effort it would take to take one approach over another), etc.

I am not personally familiar with GData or YouTube API's, so their techniques are unknown to me. However, I can make the following personal recommendations:

1) I would suggest you avoid direct HTML inspection of your page and instead recommend a server side API to complement your client side API. Specifically, I would consider a RESTful like approach where you treat your entities/data as resources for which you wish to act upon.

This approach has the benefit of being independent of the actual view/HTML representation of you page, and therefore more resilient to changes. If you write an API directly against your HTML, any time you change your page around (even if the content/data remains the same), you will run the risk of breaking the API.

Another benefit of having a server-side component is you would be able to take advantage of JSONP which can alleviate some of the pains involved in making cross-domain requests. One downside of JSONP however is you cannot make POST requests, only GET requests, which doesn't entirely jive with a RESTful approach (but I still believe a RESTful architecture offers many benefits).

2) Data transmission is an easy recommendation - hands down I would choose JSON. There are some scenarios where XML may be more apprioprate data format over JSON, but by and large I think you will find JSON will suit your needs quite nicely.

3) Client-side authentication can be difficult for cross-domain requests. One option here is to use an iframe to do authentication. Another option is to use HMAC's or OAuth.

4) As for actually writing the JavaScript API, I would recommend reading up on some of the threads here on SO regarding JavaScript books. The will likely include discussions on namespacing and other topics useful for organizing an API.

As I said - these are very generic recommendations. Could be your use-case will do just fine with a quick-and-dirty HTML scraping (though you'd likely need to use IFrames to get around cross-domain limitations). What I've mentioned above, taken as a whole, is no trivial task, particularly if none of these elements are in place right now.