Types of APIs: Web & Web Service
APIs (Application Programming Interfaces) are leveraged by developers to add functionality to an application so as not to have to write all of the code themselves. Additionally, APIs allow for accessing data from other applications — think sidebar advertisements, a request is sent to an API and if successful a response that includes data related to the ad is sent back, this data can then be displayed to the user on the webpage. If you are unfamiliar with APIs I have a brief post covering the basics of what an API is:
In this post I will be focusing on the different varieties of APIs, their use-cases, and what makes them better for different applications.
Web API
A web API is a software interface that allows two applications to interact with each other without any user intervention. There are four main web API types, Open API, Partner API, Internal API, and Composite API.
- Open API — aka ‘Public API,’ have no restrictions on who can access as they are publically available. The main priority of any Open API is ease of consumption and access to as many different clients as possible.
- Partner API — developers need specific rights or licenses to access a partner API as they are not available to the public. Partner APIs are typically exposed to a public API developer portal, from which developers can access them as they wish. While the Open API is completely open, Partner APIs involve an onboarding process that requires specific validation to gain access.
- Internal API — aka ‘Private API,’ exposed only by internal systems. The primary use-case for an Internal API is internally within a company. An Internal API is used among various internal teams of a company to improve products and services.
- Composite API — as the name suggests, this API combines different data and service APIs. A Composite API’s functionality is characterized by a sequence of tasks running synchronously as a result of execution, as opposed to the result of a task request. The primary use for a Composite API is to speed up the execution process as well as performance improvement for listeners in the web interface.
Web Service
In addition to these four main web APIs there are web services. A web service is a software or system that uses an address (URL in the case of the World Wide Web) to provide access to its services. It is a collection of open protocols and standards that are widely used for exchanging data between systems or applications.
The most common web services are SOAP, XML-RPC, JSON-RPC, and REST.
- SOAP — (Simple Object Access Protocol) uses XML as the data transfer format. The primary function is to standardize the structure of the methods and messages of communication — request and response messages as well as the structure of payloads rely on XML data format. Compared to other web service APIs (such as REST), SOAP is less flexible, but many prefer the datatype control, structure, and defined standard of this API. SOAP is used by both private and public APIs as an interface.
- XML-RPC — (Extensible Markup Language) this protocol uses a specific XML format for data transfer, whereas SOAP uses a proprietary XML format. XML-RPC is much simpler than SOAP and uses the minimum bandwidth. XML-RPC utilizes remote procedure calling using HTTP to transport and XML for encoding. It is designed to be as simple as possible while still allowing complex data structures to be transmitted, processed and returned.
- JSON-RPC — (JavaScript Open Notation) Similar to XML-RPC, this protocol uses JSON format for data transfer as opposed to XML. The open standard format subscribes to shared conventions focus on web applications and help to increase productivity and take advantage of generalized tooling. An advantage of JSON API is that is reduces the number of requests and the amount of data transmitted between servers and clients.
- REST —(Representational State Transfer) unlike other web services, REST is not a protocol, rather it is a set of architectural principles or restraints — i.e. it can be implemented in a number of ways. REST service requires certain characteristics, easily identified within the request. When a RESTful client request is made, the REST API transfers a representation of the state of the requested resource to the endpoint. This representation can be delivered in one of several formats through HTTP — JSON, HTML, Python, plain text, PHP, or XLT. JSON is generally the most popular as it is language-agnostic and can be read by both machine and human. Additionally, headers and parameters are important to the HTTP methods of RESTful API HTTP request — important identifying information is contained within.
