ABIS Infor - 2016-04
APIs
Abstract
The term API (Application Programming Interface) has been around for ages, but since a few years it got a new and very specific meaning in software architecture, as a sequel to the SOA hype (Service-Oriented Architecture).
Application Programming Interface
The generic, long-standing definition of an API goes more or less like this: it is a specification of how an application program should communicate with another piece of software, for example with the operating system (e.g. the Windows API) or with a database (e.g. the ODBC API and the Java JDBC API) or with any library, framework or software component. These specifications may cover several aspects, such as the syntax of requests and responses, the semantics and contract (what to expect), and -- according to some -- also the protocol aspects (how to get there, how to exchange requests and responses).
Web Services
The more recent talk about APIs is in the very specific context of Web based applications.
In the beginning of the 21st century, SOA (Service-Oriented Architecture) emerged as a promising software architecture paradigm: software should be able to remotely consume services (= pieces of functionality), provided by other software, running on any platform, programmed in any language, sitting in any location (as long as both parties are connected by a network).
The most popular way to realize this SOA pattern, was with Web Services (a W3C standard): formulating requests and responses in XML and sending them to the other side as SOAP envelopes, over well-known internet protocols such as HTTP and SMTP, or over a messaging service (e.g. with JMS). Such web services could be documented (described) formally in a WSDL file (XML again...), which in turn could serve as a basis for automatic generation of e.g. the client software.
The SOAP & WSDL standards are quite complex and heavy, a.o. because they are open for extensions (e.g. SOAP headers can accommodate additional standards such as WS-Security and WS-Addressing). Besides that, the XML itself is also rather verbose.
Web APIs
Starting around 2005, a more liteweight web service style gained popularity: RESTfull web services, leveraging the web as a collection of 'resources' (data) that could be used and manipulated with mostly standard CRUD operations over HTTP (GET, PUT, POST, DELETE), whereby often XML as a data format was replaced by JSON (a.o. for compactness). This architectural shift also changed the way of describing and documenting the service: it turned more or less back into a classical API 'reference' manual, with syntax and code samples, that could easily be copy/pasted into the application under development. Gradually, the term API got in use for indicating the web service API, regardless whether SOAP or REST (or other), regardless whether XML or JSON etc.. By extension API is even used as a synonym for the service it is describing, and the endpoint (= the place where it is running).
API Example
The original web services with SOAP & WSDL were readily adopted by the corporate world (for enterprise application integration and B2B applications) and by government authorities (e.g. the Belgian Crossroads Bank for Social Security). On the other hand the push for new-style RESTful APIs came mainly from social media and internet giants like Google, Twitter and Facebook.
Here is an example of how to find geographical information through GoogleMaps API:
https://maps.googleapis.com/maps/api/geocode/xml?address=Diestsevest+32,Leuven
just type this URL in your browser (it's a simple HTTP GET) and you will get an XML file with all the geocode details....
.... <location> <lat>50.8856421</lat> <lng>4.7099484</lng> </location> <location_type>ROOFTOP</location_type> etc ....
You want JSON instead of XML? Guess how... Or consult the API documentation at
https://developers.google.com/maps/documentation/geocoding/intro#Geocoding
So if you want to incorporate geocoding functionality in your own application, you just have to learn how to handle HTTP and XML (or JSON) in your programming language.
And even that skill is not indispensable: Google, like many other API providers, offers wrapper libraries for most popular programming languages, so that it finally boils down to something like this (in a syntax your are familiar with):
... getLocation ("Diestsevest 32, Leuven") ...Authentication and authorization
As demonstrated, consuming an API is rather straightforward, so great care will be needed to prevent abuse. Here are some concerns.
First, the API provider wants to know which apps are incorporating his API, for several reasons: to ask money for using the API, or for tracking purposes, or to avoid overloading the API server. Typically all this is made possible by appending an API key to each request. Such an API key can differ per application and/or per developer and per API, and it can be linked to authorizations, tariffs, quota (how many calls per time period), etc.. Sometimes the first, light usage is free, and you pay for heavier use / commercial use (freemium model). Example of a GET call with API key:
https://maps.googleapis.com/maps/api/geocode/xml?address=Diestsevest,Leuven&key=1234
While the above is mainly about authorizing the developer and the app, there is another question: who is the user of this app and does he have the proper authorization to access the data? E.g. the Twitter API allows full access to tweets and profiles, but a given user will probably only have write access to his own profile.
This kind of authorization is achieved mostly through a 'third party' authentication scheme, so that the actual application does not see or handle the user's credentials. The most popular standard for this is OAuth 2.0.
API portal
An enterprise that offers APIs, often organizes an API Developer Portal with functions such as
- API reference and documentation
- API test console, so that a developer can try out the API, live, with sample data
- wrapping libraries (e.g. for JavaScript, Python, Java, PHP)
- registering and obtaining API keys
- discussion forum and blog
Conclusion
Modern RESTful APIs are considered now as a developer-friendly way to 'expose' the enterprise back end. This article took a look at it from the developer's point of view. On an other occasion we might talk about APIs from the provider's point of view, with issues such a designing good APIs, testing, lifecycle management and versioning, API gateways and proxies, traffic control, analytics etc.