- Feb 20, 2012
- by Brad Litwin
Every developer must deal with APIs. They exist in theory to make life easier. A well designed, implemented and supported API will do just that. It will give you a standard, defined interface for interacting with other software without having to worry about its inner workings. Of course, a poorly executed API can sometimes be worse than no API at all. At least in the latter case you might be able to legitimately say “It can’t be done.” and move on to another problem.
In the wide world of web development (pun intended), APIs can be implemented in any number of ways. Not only that, different aspects of them can be implemented in a dizzying array of fashions. This can become a nightmare when you have a single project which is dealing with multiple APIs, each of which has its own authentication scheme, request method and output format.
That’s why API standards like SOAP and REST arose; to try to give API designers a standard to support which would make everybody’s lives easier. SOAP was not without its supporters and its advantages, but at this point RESTful web services are the new standard, and with good reason.
An API or service which is designed to be RESTful (that is, to adhere to REST standards) will take advantage of the multiple verbs (or request types) that HTTP supports. These include GET, POST, DELETE and others. They also take advantage of the syntax of URLs in order to make request formats logical. Once you know the principles of REST, it’s easy to predict what the format of a command you might want to do would be.
For example, if you have a RESTful service that lives on rest.foo.com and you want to find out information about user number 5, your request would probably be “GET http://rest.foo.com/users/5”. If on the other hand your form just took the registration of a user and you want to add this user to the service, you might make a request like “POST http://rest.foo.com/users” with the appropriate postfields. In general, REST uses a combination of the HTTP actions available to us, plus the nouns that you want to do these actions to in order to form a logical URL.
If I ask you to give me the request you might make in order to find all users with a firstname field of “John” you can probably guess it would be “GET http://rest.foo.com/users?firstname=John”.