One of the great things about our directory data model is that it allows us to get a big picture view of what an API looks like in today’s world. When ProgrammableWeb changed it’s directory model in 2014, we decided to allow for a more detailed way to describe an API. Among the many fields we added were three that we feel are core to describing how an API works; the API type, architectural style and scope. This month we take a look at what the data in those fields tells us about the APIs in our directory.
API Type is a field that’s powered by a drop down with five choices; Browser, Product, Standard, System/Embedded, and Web/Internet. We define these types the following way:
Web/Internet - This is a network API that is uniquely addressable across the Internet
Product - An API that is networkable, but it’s built into a product in a way that those who install that product inherit the API. Examples might be the networkable APIs that come pre-built into products that you install like SugarCRM.
Standard - Standard APIs (or proposed standards) are non-browser API specifications that other APIs might comply with. Examples of this are Google's Mobile Data Plan API Specification or the various OpenStack API Specifications for which there are multiple implementations. Another example would be the W3C version of the Web Audio API. It is a specification that providers must adhere to when creating their own implementations of the API.
Browser - These are APIs that can be found in the browser itself for enabling Web apps. For example, Mozilla’s implementation of the Web Audio API.
System/Embedded - These are APIs that are mashable into Web apps but that might be specific to a local operating system or device. For example, the API used so that a Web app may access the fingerprint sensor on a smartphone.
The first thing we see is that the vast majority of profiles do not have a value selected for API Type. This field was not available before our migration in 2014 and one of our ongoing efforts is to update records that preceded our new data model. Of the remaining 3,620 APIs that have a value, we see that the great majority of them (82%) are web/Internet APIs(see Figure 1 below). This is no surprise as ProgrammableWeb’s mission has always been to chronicle the web as a platform and APIs addressable over the Internet have been key to that.
Figure 1: The percentages of API Types for profiles containing non-null values in the ProgrammableWeb API directory
In the past, if a provider offered an API that was RESTful in nature as well as one that supported Webhooks, ProgrammableWeb listed those under a single API profile. While it made for a more succinct directory, it failed to capture the truth that there were multiple APIs with different endpoints in use. The styles we track include.
REST - Obviously this is for a RESTful API. We are not adhering strictly to Fielding’s definition of REST but, simply talking about APIs that use HTTP methods to facilitate communication between a client and server.
RPC (Remote Procedure Call) - This is for Web services related APIs that typically involve SOAP and XML-RPC but we've seen others. It is used when an API calls a known procedure on the Web service other than using the supporting protocol's built in verbs.
Indirect - This is used when an API is only accessible indirectly through an SDK. An example is the Evernote API that is only made accessible via the various language SDKs. The reason we create this sort of "stub" entry for an API that technically doesn't exist is so that it's easy for audience members to find their way to the SDKs, if they exist.
GraphQL - This is a somewhat newer API technology that we just recently added to our list of architectural styles. GraphQL APIs have a hypermedia-like ability to use a single query to fetch the required data across multiple resources. But GraphQL APIs also borrow from concepts that we’ve observed in both REST and RPC-styled APIs. As we say here at ProgrammableWeb, it’s neither fish-nor-fowl. As such, we’ve established a separate architectural style just for GraphQL.
As expected, REST is by far the most commonly used architectural style given its prominence in API design over the last decade plus. RPC is the next most commonly used, owing to the many SOAP and XML-RPC-styled APIs that appeared, especially in the early days of our directory. Google’s gRPC APIs also fall under this style. GraphQL is still in the early days as far as having production ready APIs with Yelp and Github being the two most notable providers to use this style as an alternative to REST.
Figure 2: The percentages of API Architectural Styles for profiles in the ProgrammableWeb API directory
What about your API; does it adhere to the types and architectural styles most commonly used? If you are a provider adding a listing in our directory is a great way to improve the discoverability of your APIs and raise awareness of your program. If you would like to include your APIs in our directory, you can use the link below.