Api Functions

What is api ?

What is api?

API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. Each time you use an app like Facebook, send an instant message, or check the weather on your phone, you’re using an API.

In computing, an application programming interface is an interface that defines interactions between multiple software applications or mixed hardware-software intermediaries

What are APIs used for?

An API (Application Programming Interface) is a set of functions that allows applications to access data and interact with external software components, operating systems, or microservices. To simplify, an API delivers a user response to a system and sends the system’s response back to a user.

Types of APIs

APIs by availability release policies

In terms of release policies, APIs can be private, partner, and public.


Types of APIs by availability

Private APIs. These application software interfaces are designed for improving solutions and services within an organization. In-house developers or contractors may use these APIs to integrate a company’s IT systems or applications, build new systems or customer-facing apps leveraging existing systems. Even if apps are publicly available, the interface itself remains available only for those working directly with the API publisher. The private strategy allows a company to fully control the API usage.

Partner APIs. Partner APIs are openly promoted but shared with business partners who have signed an agreement with the publisher. The common use case for partner APIs is software integration between two parties. A company that grants partners with access to data or capability benefits from extra revenue streams. At the same time, it can monitor how the exposed digital assets are used, ensure whether third-party solutions using their APIs provide decent user experience, and maintain corporate identity in their apps.

Public APIs. Also known as developer-facing or external, these APIs are available for any third-party developers. A public API program allows for increasing brand awareness and receiving an additional source of income when properly executed.

There are two types of public APIs – open (free of charge) and commercial ones. The Open API Definition suggests that all features of such an API are public and can be used without restrictive terms and conditions. For instance, it’s possible to build an application that utilizes the API without explicit approval from the API supplier or mandatory licensing fees. The definition also states that the API description and any related documentation must be openly available, and that the API can be freely used to create and test applications.

Commercial API users pay subscription fees or use APIs on a pay-as-you-go basis. A popular approach among publishers is to offer free trials, so users can evaluate APIs before purchasing subscriptions.

APIs by use cases

APIs can be classified according to the systems for which they are designed.

Database APIs. Database APIs enable communication between an application and a database management system. Developers work with databases by writing queries to access data, change tables, etc. The Drupal 7 Database API, for example, allows users to write unified queries for different databases, both proprietary and open source (Oracle, MongoDB, PostgreSQL, MySQL, CouchDB, and MSSQL).

Another example is ORDS database API, which is embedded into Oracle REST Data Services.

Operating systems APIs. This group of APIs defines how applications use the resources and services of operating systems. Every OS has its set of APIs, for instance, Windows API or Linux API (kernel–user space API and kernel internal API).

Apple provides API reference for macOS and iOS in its developer documentation. APIs for building applications for Apple’s macOS desktop operating system are included in the Cocoa set of developer tools. Those building apps for the iOS mobile operating system use Cocoa Touch – a modified version of Cocoa.

Remote APIs. Remote APIs define standards of interaction for applications running on different machines. In other words, one software product accesses resources located outside the device that requests them, which explains the name. Since two remotely located applications are connected over a communications network, particularly the internet, most remote APIs are written based on web standards. Java Database Connectivity API and Java Remote Method Invocation API are two examples of remote application programming interfaces.

Web APIs. This API class is the most common. Web APIs provide machine-readable data and functionality transfer between web-based systems which represent client-server architecture. These APIs mainly deliver requests from web applications and responses from servers using Hypertext Transfer Protocol (HTTP).

Developers can use web APIs to extend the functionality of their apps or sites. For instance, the Pinterest API comes with tools for adding users’ Pinterest data like boards or Pins to a website. Google Maps API enables the addition of a map with an organization’s location.

6 Characteristics That Make an API Great for Application Integration

Two methods to integrate with the help of API

Before I get to summing up characteristics of an API that would make integration a breeze, let’s quickly get through the basics of integration via APIs.

Basically, the mechanics of application and data integration is different depending on the quality of an API. You can either actively fetch data by polling an API or let an API send you data. Both methods have their pros and cons.

When you poll an API, you are in charge of data flow. If you need more data, you just specify that. If you know you have already too much of it so that it already got stuck somewhere along the way, you just decrease the amount of data you receive per request. This is important, because being in control of your data flow is highly relevant for a better performance of your integration as well as for guaranteeing that the data won’t get lost in case your storage is full.

The most obvious disadvantage of this method is that it can fail to deliver data in a real time mode. When you poll an API, you need to define clearly how often this will happen. Theoretically, you can poll it every other second, but most good APIs would impose limitations in terms of how often you’re allowed to do that and how much information you’re allowed to fetch in one go. So, let’s say you can schedule polling every three minutes. If data is processed faster than it is received, then you are bound to have delay in data processing.

The other method involves setting up a webhook trigger. In this case, an API would send data to webhook triggers on its own while they would just sit there and wait for it. It can be considered as an ideal solution, because then it doesn’t really matter how the API looks like. All you need is for the sending system to deliver data as soon as it is changed.

Another advantage is that you would have very little to no delay between data receiving and data processing, because it will be automatically processed as soon as it arrives.

But the drawback of this method is, opposite of polling an API, the lack of control of the data flow. The sending system will just keep delivering the same amount of data over and over again as soon as it will get confirmation that the previous batch was indeed delivered and e.g. stored in the message queue. There will be no way of limiting the amount of incoming data in case of emergency.

6 Characteristics That Make an API Great for Application Integration

6 Characteristics That Makes API Ideal for Integration

An API that is a best fit for integration purposes is actually suitable for both methods described above. Sometimes, though, one is preferred to the other. And while the second method is more or less universal (if you remember, with webhook triggers, we don’t care about the quality of API), it is the first method that reveals if an API is good or not.

So, what are the qualities of a good API for integration and why are they so important?

1. Modification timestamps/ Search by criteria:
A good API should allow to search data by certain criteria, most importantly by its date. Simply because after the first initial data synchronisation, it is typically the changes that we are mostly interested in. In other words, we need the changed (updated, deleted, corrected, etc.) or added information since the last time we triggered the synchronisation.

So, when a trigger should poll data from API, the first important question to answer is how to detect changes in data.

The only way to get this data is to start asking for changes since particular timestamp. For example, the first, initial data synchronisation happened on May 01, 2016. So, we specify this date as a point of reference, and set up to request for data that has been coming in since this date. This is why it is important that in addition to search by criteria option, an API also provides timestamps.

2. Paging:

Naturally, it can happen that there are huge amounts of data, even if this is only the changed data. In order to deal with it efficiently, we need to have a way to specify that we need not all the changed data in one sitting, but, say, only the first “page” of it. For example, of the size one thousand data records.

This is what paging is about. A good API must be able to limit the amount of data that can be received in one go, as well as the frequency of requests for data. It should also be able to notify about how many “pages” of the data are left.

3. Sorting:
Paging can only work, though, when data is ordered, because if it’s not, it is impossible to know whether you’ve already received that data or not. Therefore, an API should also be able to allow to sort data at least according to time of modification.

So, having all these three characteristics allows us to define that we only need the data that came in after May 01, 2016, and only the first “page” of it, in our example, one thousand data records, ordered by time of change. Then we’ll remember what was the changed timestamp of the last record in this one-thousand records list, and then ask for next batch of data only starting from that moment. The mechanism for remembering timestamps can vary; we, for one, use snapshots for that.

Having said all that, if you use the OData protocol (preferably the latest version 4) to create APIs, then they will possess all the characteristics mentioned above by default, as well as some other, quite important ones like upserting an entity or conflict resolution (to avoid duplication of data).

4. JSON support / REST:
To be fair, an API doesn’t have to be RESTful in order to be considered good. However, most new APIs are REST APIs that, by default, support JSON, and there are quite a few good reasons for that.

REST APIs are stateless, which makes them ideal for applications that require a considerable amount of back-and-forth messaging, e.g. for mobile apps. If an upload to a mobile application is interrupted due to, say, loss of reception, REST APIs make it very easy to retry the process. With SOAP, this is possible too, but with considerably more effort. In addition to that, REST APIs are lightweight and more compatible with the web as they use simple URIs for communication.

REST APIs support various formats, with JSON being only one of them; TXT, CSV and XML would be other examples. This means that you as a developer has a choice between different formats (as opposed to SOAP that supports only XML), and can go for the one that really fits the purpose.

Using JSON with REST is considered to be best practice, though. Mainly, because unlike XML, JSON’s syntax is very close to most programming languages, which makes it very easy to parse it in almost any language. Not to mention that JSON is also really easy to create.

5. Authorization via OAuth:
OAuth is an open standard for authorization, and even though it is considered by some developers to be a pain in the …hm.. neck, OAuth provides considerably better usability for the application users/developers than any other method.

Contrary to widespread beliefs, OAuth isn’t equal to signing up with your Facebook or Twitter account; OAuth means that if application users (e.g. Xero users) want to connect this application with another one via some integration services, they can authenticate themselves by explicitly granting this service access to the application – no more, no less.

Unlike granting access with, for example, an API key, though, the OAuth authorization is considerably faster – you just need to click on a button confirming access grant. Any other method means that users of your API have to actually make an extra effort – not great for delivering superb user experience.

6. Good documentation:
It is last, but not least.
It seems like providing a good, extensive documentation for an API is something that should be understood by developers by default, you don’t need to point that out. Yet there is a massive amount of APIs that are extremely poorly described, even those APIs that are actually very good for integration.

Therefore, we can’t stress this enough how providing a solid documentation for API is important for integration projects, because it is one of the factors that drives the decrease in project implementation time, and hence, in costs for the project. And a good documentation surely does add up popularity to an API;-)

Related Post

Leave a Reply

Your email address will not be published.