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.
- You could have a web page on your site
that pulls data from the web service and displays it to the user of
your site. In this case the interaction with the web service is between the viewer
of your site and the web service. Your site never sees the retrieved
data. Here's a static page of mine that has javascript that calls
the patentsview web service. The static page comes from this site
while the data comes directly from the patentsview web service,
my site doesn't see the patentsview data. It's asking for the most
recently issued plant patents. The data returned will change over
time as more patents are added to the patentsview database.
- You could have a program on your website that is activated when
a user requests a specific page on your website. The program could
call a web serice directly and do something with the data to dynamically
generate the web page that the user sees.
- And finally, you could write a smartphone application that
retrieves data from a web service and uses that data in
some way (displays text or a map etc).
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