API 101

This is a short explanation of api's and their associated web services. We start with the familiar web page and then dive deeper.

Web Pages

Typically a web page is a physical file on a server somewhere on the internet. It could also be generated by a program backed with data from a database on a server somewhere.

Examples:

API/web services

If someone puts up a web service on the internet, a couple additional options become available. In the web service examples above you could really be using more than one web service call to retrieve data. The calls could be going to the same web service to get two different data sets or to two different web services. Here's an example where a static page on my website calls a web service on my site and then calls the patentsview web site in order to get the data that is displayed to the user.

Here's a more involved static page on my site making multiple calls. The javascript on the page hits a web service on my website. If a user hits the Get More Cities button another call is made to my web service. If the user clicks the Details link on the web page a web service call is made directly to the patentsview web service and the results are displayed. If the user hits the Map It button a call is made directly to the google maps web service.

Bulk Data

Some web service providers make their raw data available to be downloaded. I downloaded the location data from patentsview.org in order to write my own web service. From a giving latitude and longitude it will supply the locations of the five nearest patent cities. This is something not provided by the patentsview web service. I can now write web pages or phone apps that call my web service. The web page or phone app can retrieve the data from my web service and then make additional web service calls to the patentsview web service to retrieve more data about these locations.

APIs

The api provided by the web service provider explains the ways in which their data can be retrieved. Typically a web serice is like a Swiss Army knife, capable of returning data is lots of interesting ways. As a consumer of the web service you need to know how each blade in the knife works in order to retrieve the data you want from the web service. The api provider gets to make up the rules as to how interactions take place, what parameters are required, which ones are optional etc.

Api Clients

A web service provider may provide a client (web page) that hits their own service. They can be powerful and may do what you want it to do so you wouldn't have to write your own client. Their client can be used to directly pull data etc but the real power of a web service comes when you write your own client for your web site or mobile app. Using the patentsview web service as an example, you can write something that displays patent data in a way no one else on the web does, including the patent office themselves! Plus its data is provided by the patent office for millions of patents that they maintain and add to as new patents are issued. All you have to do is tap into their web service. Really helpful and forward thinking web service providers will provide a test client to aid developers in understanding the nitty gritty details of the client/server interaction. One such opensource framework is Swagger, available for free at Swagger.io. Here's the Swagger Interface for the patentsview api. It lets developers interact with the web service in exactly the same way the clients that those developers will write, once they learn the ins and outs of the web service.

Next