For a lot of people the concept of a REST API might be relatively new. Some of you may be completely new to the subject with only limited experience with web development. Others may be more familiar with SOAP based APIs with their verbose and often complex XML. One of the big differences between REST APIs and the API styles that came before it like SOAP, is how the APIs are structured. SOAP based APIs are structured to have 'methods' that return data, much like object oriented computer languages. Method names are formatted like 'getAllCustomers', 'getProductByNumber', 'updateCustomer', things like that. Notice the 'verb', or what you want to do with the data is part of the method name. All the communication can be over HTTP, and the URL to access the service doesn't change with each call. All the information the service needs is sent to the service in an XML document.

Things are a little different with REST APIs. First, REST is not a standard like XML or SOAP. RESTful APIs will usually adhere to certain design principles, but not actually required to. This means that not all APIs will look or act the same. Designers of REST APIs want their APIs to be easily understood, so people usually stick pretty close to the 'rules'. There are lots of tutorials on the web about what these 'rules' are, like the O'Reilly book 'REST API Design Rulebook'. It's short and hits all the main points.

Another difference with a REST API is that the URL is key. Accessing different parts of the API are done through different URLs. Similar to a hierarchical file system, REST deals with collections (like a folder) and objects (like a file). So, the 'customers' collection represents a list of all the customers. You reference an individual customer as a descendant of the 'customers' collections using the ID (id can be anything that is meaningful for your data set, a number, a name, etc.) for the customer record like:

http://api.example.com/customers/123456

The final big difference with REST APIs (at least for the purposes of this discussion) is that the verb is not part of the request to get the resource. So you wouldn't use getCustomer/1234... but wait... in a way, you actually do! REST uses the HTTP protocol to communicate between client and server and HTTP actually has the 'verb' part built in! Normally when you use a tool like a web browser, this kind of stuff is all done behind the scenes. Part of the data that HTTP uses to ask a server for a resource is called the 'method'. There are 8 methods defined by the HTTP/1.1 spec - OPTIONS, HEAD, TRACE, CONNECT, GET, POST, PUT, and DELETE. If you have ever done any web development you are probably familiar with GET and POST, and some REST APIs takes advantage of PUT and DELETE as well. REST APIs are designed around the use of the HTTP method to tell the server what you want to do with the resource URL you have requested. So, to retrieve the data for customer 1234 you would use the GET method with the URL 'http://api.example.com/customer/123456'. If you wanted to update that customer record you would use the PUT method and send an updated record body to the same URL.

Ok, so lets put this into some context. The Infoconnect API has 4 APIs (or collections). All of our APIs are read only, so we don't support PUT or DELETE. However, each of the endpoints supports at least GET and some support POST.

The most basic version of our GET API will include a record ID. Just like we talked about earlier, to get a particular record in a collection you use the 'collection/id' URL. So to get a single record from the companies collection I would use this:

https://api.infoconnect.com/v1/companies/826381212&apikey=

(NOTE: you will have to add your API key to the end of this URL for this to work)

The GET version of some APIs can also be used with simple search criteria which are included in the query string portion of the URL. So, if I don't know what the record ID is, I can look for things like a company name or phone number. For example, if I know the phone number I can use this:

http://api.infoconnect.com/v1/companies?phone=4028364500&apikey=

(NOTE: you will have to add your API key to the end of this URL for this to work)

However, some of the search criteria can get pretty complex, so to make things a little more convenient, some of the APIs use POST to allow you to send more complex search criteria to the API. With the POST method of the companies search API you provide all your search criteria as either JSON or XML in the body of a POST. So, for example, you can search for all the companies with 50 employees, is in Massachusetts, and is a franchise. The URL is pretty simple for this query:

https://api.infoconnect.com/v1/companies/search&apikey=
(NOTE: you will have to add your API key to the end of this URL for this to work)

Then in the actual body of the POST we submit the following data:

{
    "LocationEmployeesSizeRange": [ "50-99" ],
    "StateProvince":"MA",
    "IsFranchise":"True"
}

And voila! Looks like there are a lot of Applebee's that fit that profile... go figure.