Application programming interfaces (APIs) are now a well-known concept in application integration. But people forget that they were only introduced in 2000 when companies like Salesforce, eBay and Amazon launched. Since then APIs have become indispensable for various apps, particularly mobile, SaaS and cloud, and customers have come to expect integration via APIs. The Flowgear platform provides support for the full API lifecycle. We thought we would help developers starting on an API project with some tips on what to do.

What is an API?

An API is an interface that allows software programs to interact with each other. APIs define the rules and data structures that should be defined so that applications can communicate.

The importance of APIs

No matter whether your role is to manage applications or develop them, you know that you have to at least consider an API strategy for the software you manage. According to Programmable Web’s API directory, there are over 16000 APIs published (as of this date), and that number is growing by several thousand every year.

The reason why APIs are growing in popularity is because businesses and their systems are increasingly being connected electronically. APIs make the process of integrating with customers, suppliers and other participants in your ecosystem easier – and making your business easy to connect with is important. For example, Amazon’s Marketplace Web Service (Amazon MWS) has publicly available APIs which help Amazon sellers to programmatically exchange data on items like listings, orders, payments and reports. This has attracted over 2 million sellers to MWS.

APIs are not just a ‘nice to have’ feature any more. Their development and use needs to be managed as an important IT and business asset.

Benefits of APIs

APIs vs SDKs

There are two ways to interface a program with another piece of software – APIs and SDKs (software development kits). The difference between the two is that an API is an interface, whereas an SDK is implementation tooling.

APIs are like Lego blocks that a child can play with to join blocks in different shapes. Any software that presents the right security credentials (if required) can use an API.

An SDK is like a workshop where development tools are available, rather than pre-shaped building blocks. You can make your own blocks, or create something without using any blocks.

An API can be viewed as a simple SDK without all the detailed technical baggage. It is far easier and quicker for third party developers who don’t know the intricacies of your system to use an API than an SDK.

What transport protocols to use

Transport protocols establish an Internet connection and ensure data integrity. In the past, the common transport protocol was SOAP (Simple Object Access Protocol), but this is being widely replaced by REST(Representational State Transfer).

The problem with SOAP is that creates a cluttered payload, and can only use XML(eXtensible Markup Language) for defining and encoding data.

REST is much leaner on data, and can use both XML and JSON((JavaScript Object Notation).

Source: http://stackoverflow.com/questions/209905/representational-state-transfer-rest-and-simple-object-access-protocol-soap

XML vs JSON

You need to consider what data format your API will support. The choice is XML or JSON, and there are pros and cons to both.

While XML is still commonly used, it has disadvantages, such as:

• XML files can be bloated
• XML is less readable by humans

On the other hand, JSON is more compact and more readable.

An advantage of XML is its powerful data formatting capability which you can use for organizing and structuring information using attributes and namespaces. However, if you only need to exchange data, the simple data format of JSON makes it lighter and faster.

Designing an API

If you have followed the recommendations so far, you are planning a RESTful API. Several books have been written on how to design and build APIs (here’s a list at Amazon), but here are the basic concepts to be aware of.

Business requirements

APIs are not created spuriously but as part of a business objective. While you are building an API you therefore need to know those underlying requirements and goals. Otherwise the API will be a waste of effort and money.

Data design

The first step is to decide how the data will be designed and how your core service will work. If you’re starting an application from scratch this shouldn’t be too difficult, however if you are building an API for an existing system, you may need to provide some abstraction.

Resource

Your API should be separated into logical resources which are manipulated using HTTP requests GET, POST, PUT, PATCH, and DELETE. A resource should be a noun that make sense to the API user. Examples of resources are ticket, account, user, stock item. You will of course need to provide return information when a request is executed. For return codes, a useful list of HTTP status codes can be found here.

Security and authentication

You will probably want to have some security around the data and application that your API is built on, so you will need to have authentication. This can be done either via a user ID, or using a token; make sure the token has an expiry policy. OAuth is a common standard for authorization. Also, ensure you use SSL (Secure Sockets Layer) to ensure an encrypted link between a web server and a browser.

Versioning

You should always version your API. Versioning helps smooth over any major API changes as you can provide backward compatibility and continue to offer older versions for a period of time.

Documentation

You can have a fabulous API but it will be a failure if the documentation is poor. Provide a wiki site for information, and also make documents available in PDF so they can be printed or stored offline. If possible, provide a test harness or sandbox so developers can experiment.

API user experience

When building your API, keep these factor in mind. An API:

• must appeal to developers through ease of use, benefits gained, and user acceptance,
• should be friendly to the developer and be explorable via a browser,
• should be simple, intuitive and consistent,
• should be efficient and flexible.

Support different types of API users

Until recent times the only people who accessed APIs were developers, but with the rise of ‘citizen integrators‘ your API may need to support non-technical users performing their own integration tasks.

APIs are the future

APIs are not just something for an IT department to consider, businesses should be looking at the benefits of APIs as the modern software approach to being inter-connected. Business objectives, especially digital ones, can be supported by an API strategy. That is why API implementations need to be planned and built with organizational goals in mind.

Flowgear allows developers to build APIs that consolidate data sources from multiple systems, integrate different applications and devices, enable the transition from one system to another without changing the portal through which people and applications access data, create a uniform structure for allowing communication between new and legacy applications.

The Flowgear platform supports the API development lifecycle:

• Design
• Test
• Prototype
• Deploy
• Support authentication
• Versioning

To learn more about implementing an API, see our Developers Help.