February 8th, 2010

What is an API?

By James Wilson, VP of Development

First… it is an acronym

API is an acronym which means Application Programming Interface.

What is it?

It is a contract that allows computers to talk to each other. Another name used widely is a protocol which is a set of rules that must be followed to exchange information. By “talk”, I mean the ability to ask a question and get a valuable answer back.

How does it work?

A really smart computer person (a developer) defines and builds a system that accepts questions (request for information). Next, that same developer writes instructions (the contract or protocol) that must be followed in order to properly accept questions so that the valuable answers can be computed and returned. Another developer, somewhere else in the world, reads the fascinating and tantalizing contract documentation. She then sets out to build a unit within her own system to ask questions at the proper time. Her system then uses the subsequent answers to deliver great value to that system’s end users.

What should be in an API’s contract?

1) Location, Name and Protocol

• Mechanism or protocols to be used to establish a connection. These are typically another lower level type of API or contract.
• The address or location of the system that can answer the questions.
• Name of the service.

Let’s give an example of a typical business to business (B2B) scenario. Just below is a URL or web address used to locate a service which finds nearby pizza delivery services.

http://www.pizza-store-locator.com/service/find-the-closest-pizza-delivery

The protocol used is established with the text: “HTTP”. HTTP is another acronym which stands for Hypertext Transfer Protocol. This is another contract which specifically defines how a web browser, like FireFox or IE, can communicate with a web server. Many higher level business services are built on top of this lower level API.

The location of this API is defined as “www.pizza-store-locator.com“. This type of string is typically called a domain in web parlance.  A domain is always associated with an IP address. This is a unique identifier and allows request to be reliably routed to the appropriate web server. An IP address is an acronym meaning “Internet Protocol” address. There is that word, “protocol”, again. The whole WWW, World Wide Web, is just a series of layered protocols that allow everyone to talk to everyone else.

The name of the  service is “service/find-the-closest-pizza-delivery”. This name is mapped to business logic, or a program, on the web server in this case that is responsible for formulating an answer. Just guessing, but this service probably helps find pizza delivery services. It is nice when the name of a service is self describing!! That is the sign of a good API.

2) Input Definition

• What questions can be asked?
  • Is there only one questions or different types of questions?
• What are all the pieces of information that must be included in the question so I can answer it?
  • In the example above, for the pizza delivery service, what information is required to find the closest pizza delivery shop? The contract could specify an address is required like 90 Broad Street, Suite 2002, New York, NY.  But it could also just be a latitude and longitude.
  • Lets keep going… how far away are you interested in searching? 5 Miles, 10 Miles or do you care? No, you don’t because it is not you that must do the driving to the pizza shop so… perhaps you only want a certain number of shop results back like 20 or 5? Perhaps you do need 20 but want to have at least 5 different pizza shop options returned so you can get a good selection.
  • All this stuff needs to be defined by the service creator based upon research by a product manager into how people actually think and what they want.
• How should all of those pieces of information be structured?
  • There are many ways to send information to the service.
    • We can send it as query string parameters.  For example..
      • http://www.pizza-store-locator.com/service/find-the-closest-pizza-delivery?LATITUDE=108&LONGITUDE=-47&number-of-different-types-of-shops=10.
    • We can send it as XML
      • <latitude>108</latitude><longitude>-47</longitude><number-of-different-types-of-shops>10</number-of-different-types-of-shops>

3) Outputs

• A description of the answers that can be returned
• Format of the answers
• Exceptions or errors that can be expected
  • A good API will defined all of the possible bad scenarios that can occur and how it will notify the calling program. This allows the calling program to respond gracefully.
  • Here are some examples to possible bad return results:
    • Not enough information was submitted, and here is specifically what was missing: the latitude.
    • The service is temporarily down.
    • The service is too busy, please try again later.
    • No results were found.
    • Results were found but not as many as you asked for because we only search within a maximum distance of 10 miles
    • This service has moved to a new address…
    • …and so on…
  • Typically each of the possible errant answer is give a unique identifier or code which allow computers to respond easily.

An “out of this world” example…

Do you remember “Close Encounters of a Third Kind” when the scientists first started communicating with the huge alien ship that came over the mountain? Sure you do… who can forget this brilliant movie that is now such a fundamental part of the fabric of our existence. Well… in this movie, the scientist use mathematics manifest through sound and lights to try to establish basic communication with the aliens. Once the alien understood, they repeated back the message to say to the scientists, quite loudly, “Yes, we heard you!” An interface was established, an agreement that if you flash your lights and send over sound waves, we will capture that information, process it, and send you back beeps and blips along with flashing light signals too (and the result of this will be that we land our ship and change the very nature of your lives!).

References

I have listed some common websites to give other definitions of an API; however, they commit some of the cardinal sins when defining a entity.

1.     Wikipedia

1. Sin! – They use the object in the definition itself.

2.     How Stuff Works

1. Sin! – They use the noun in the definition itself.
2. And worse still they limit the definition of API’s to web technologies.  It is important to understand that API’s are EVERYWHERE… for example… inside a computer, API’s are established to allow software to run  successfully on a computer’s hardware which has nothing to do with the web.

Tags: API, Application Programming Interface, James John Wilson, James Wilson PMP, Onboard Informatics, What is?.

May 4th, 2009

Did You Know?

By Colleen Staunton, Product Manager

Now that activity seems to be picking up in a number of markets, time is in short supply for agents. There is a need to supply clients, or potential clients, with as much information as possible without spending an inordinate amount of time trying to do so. The demographic, school, nearby establishments and home sales information is the exact type of information that home buyers are looking for.

Well, how about being able to place an API on your site where a visitor can enter their name, email address and zip code to receive all of this information? And how about being able to accomplish this in 3 easy steps? The above can easily be accomplished by utilizing the API from our CoPilot product.

A little background first for those of you who are not familiar with our CoPilot product. CoPilot provides customized reports for relocation purposes or for agents looking to provide home buyers with location specific information. Reports can easily be customized with the broker’s logos/headers. Agents can even choose what data sets that they want to include, whether that be community information, school reports, nearby establishments or recent home sales transactions. One of the best feature is the ability to collect client information and track whether they are opening the reports, and even how many times they have accessed the report.

The API functionality and instructions can be found at My Profile –> API. The three steps that would be required for this type of set-up include:

1. Create your default report template. Instructions are included for this in the Administrative system.
2. Add the lead form to your website. The lead form HTML is included so all you need to do is copy and paste.
3. Customize your landing page. The landing page HTML is included so all you need to do is copy and paste.

Upon entering their information into the Lead Form, a report is emailed to the user. An agent can then follow-up accordingly.

By posting this simple API to a website, all of the hard work is eliminated from having to create individual reports each time a client makes a request for more information. Reports can even be emailed detailing recent API activity – contacts created, reports created and reports read.

This is a great way to easily distribute all of our excellent data to your clients. If you are currently one of our clients on the CoPilot platform we strongly encourage you to take advantage of this very powerful feature. For those of you who do not utilize CoPilot at the moment we would love to talk to you about it.

If there are any additional questions please feel free to reach out to me at cmckeating@onboardinformatics.com or to our Product Support team at support@onboardinformatics.com.

Let us know any feedback you may have on the API functionality.

Tags: API, copilot, Products.