What does it mean to create an API on the web?

Question

I have a site built in ASP.NET MVC and uses heavy jQuery client interaction to build a live chat room. Many users parsed the javascript and found the URLs it posted to in order to interact with the chat. They started building bots for fun to play games within the chat channels.

These users keep asking for an "API" to make it easier for them to code against. I thought I knew what an API was but I think I'm still a little fuzzy. Isn't an API any interface that a third party could interact with?

What would it mean to build a web API for my site? Would it just be a document with a list of URLs and how to interact with them?

I have also heard of web services and web references. What are they? What does it mean to build a web service? Does that have anything to do with APIs on the web?

Answer 1

An API, or Application Programming Interface, is a set of established protocols for external programs to interact with your application. As you said, the users parsed the javascript and discovered the URL's that you use, and then built programs using those URL's to interact with your app.

Technically, you already have an API, and they have discovered it - that set of URL's that controls opening chat rooms, posting to the rooms, reading others' posts. However, what your users are asking for is a more established, structured set of methods for doing this.

Such methods might include a form of authentication to the application, as well as messages and/or data passed back from the app to the external program allowing the external program to know what happened to its request (versus just HTML coming back, or nothing at all) - like "success", or "error", "unavailable try again", etc.

Answer 2

An API is, literally, an "Application Programming Interface". It is, at its most basic level, any interface designed for other software to interact or communicate with it. In a sense, your open URLs are APIs. Of course, entry points intended as user interfaces often aren't very well-factored for writing other software against, so while they're APIs, they probably aren't very good APIs, and you will probably find yourself with performance problems on your hands soon.

Web APIs are entry points on an application running on a web server that permit other tools to interact with that web service in some way. Think of it as a "user interface" for software. Your software needs proper security and access controls, however. Consider rate limiting, or you risk a very aggressive bot flooding your server. But that rate limiting needs to be in the user interface for humans, too- or someone will simply write scripts against it.

A web service is any application, running on an Internet-facing server, that can be interacted with via the Internet, generally with an API that allows other web-based utilities to use your service as part of its functionality.

A list of URLs and how to interact with them is all any web API is, in the end. Modern-day web API design almost always involves authentication and security tokens (you should probably study the OAuth authentication model used by, among others, Twitter), and there are a variety of competing standards for how to send data, of which JSON is one of the more popular options. Documenting your interface does turn it into an API, but you might want to spend some time deciding if that's really the "right" way for software to interact with your web service- once you've published an API, changing it will break anything that depends on your service!