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?
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!