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.

Bulk Data

Some web service providers make their raw data available to be downloaded.

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 Pair Bulk 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! Here's a page that uses the Pair Bulk service to search by status - something not available anywhere else. 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 Pair Bulk 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