Api Tutorial for Beginners

An API (Application Programming Interface) is a software-to-software interface that enables two applications to exchange data among each other. Though this might sound a little boring, they are used a lot in the real world to create some amazing applications. One particularly key role that APIs will be playing, in the future, is to connect to The Internet of Things.

As a simple example, Facebook has a public API that allows third-party applications to integrate Facebook. This means that a developer, for example, can allow you to log into an application using your own Facebook account. The term “integrate” means that an application is using a particular API.

Adding Facebook is just one example. There are thousands of other cases where applications integrate other services. For example, other integrations could include:

• WhatsApp integrated Google Maps so you can share your location in a message
• Spotify and many others integrated Facebook so you can log into their applications with your Facebook account
• Some other sites have integrated YouTube so you can watch videos without leaving the site

Now, you are either reading this guide because you are completely new to APIs, or you already know a little bit about them and want to now integrate them into your own applications, So how do you go about doing this? One of the easiest ways to do this is to learn in regards to making an example app, so, these are the steps you would have to take:

Beginner API App – Background

Let’s imagine you are an aspiring software developer and are designing your own app. Let’s also call this application MyApiApp. The goal of MyApiApp is to obtain the maximum benefit from the users social networks. So for example, by viewing the statuses of friends on all networks on one screen. Therefore MyApiApp shows the most important news of everyone on all of a user’s social networks. For this, the MyApiApp application has to access the functions of Facebook, Google+ and LinkedIn. To do this, we will use their APIs.

How APIs Work for Beginners – The technical details

Even if you are just starting out, you will want to know a little bit about the technical details of how APIs can communicate to services. One problem is that different APIs will communicate in different ways.

Most API’s come underneath four different types. RESTful types are the most common, and the rest of the article will be about those, but to sum up the other three:

SOAP – Simple Object Access Protocol. These exchange data in the form of an XML file (which is like a fancy kind of HTML Table document).
JavaScript – A specialist kind of APIs, these are focused around Javascript and are accessed using this language. These are only really used by Javascript and Web developers.
XML-RCP – To use these kinds of APIs, you call it using XML and it returns XML. This standard was further developed and became SOAP.

In RESTful APIs, communication between applications is done using the underlying HTTP protocol (HyperText Transfer Protocol). HTTP is widely used on the internet, and many developers are already familiar with it. In fact, this is the reason why all “true” web address start with either HTTP or HTTPS.

The simplest HTTP request you can actually make is simply opening http://www.example.com in your browser, which would send a HTTP request to that address. This means that opening up a web page is just the most public facing version of making a HTTP request. However, RESTful APIs can also use the protocol to interact with Program Interfaces.

So that the MyApiApp application can access Facebook Features, it sends an HTTP request to the Facebook servers. In the HTTP request, it is specified which function of the API the application would like to use (e.g. return profile information).

There are four major HTTP request methods:

• GET – to fetch data
• PUT – to edit existing data
• POST – to add the new data
• DELETE – to delete data

After you have sent an instruction to Facebook, using one of these methods, then the Facebook servers will process the given request. As long as valid inputs have been given, Facebook will then send back your requested data.

Now, unfortunately, both how the data has to be formatted in the request, and how to call the request, is not uniform between APIs or programming languages. However, we can give an easy, interactive, example with the Google Maps API.

When you use the Google Maps API, you get a JSON request back, which is an easy to read format for machines.

If you click on the URL below, you will see exactly what kind of data a program calling this API via RESTful HTTP would receive:

http://maps.googleapis.com/maps/api/geocode/json?address=Mannheim

As you are only reading the data, you would want to use the GET protocol, and you could do this in Javascript just like this:

var GoogleMapsRequest = new XMLHttpRequest();
GoogleMapsRequest.open(“GET”, “http://maps.googleapis.com/maps/api/geocode/json?address=Mannheim”, false);
GoogleMapsRequest.send()

This Google Maps API call returns the GeoData of Mannheim in the JSON format.

Let’s leave it here for now, because there is one major thing to consider when using APIs. That of authentication.

Many APIs require that a user authenticates themselves. On the one hand,
this ensures a degree of protection against abuse for others. This is because if a provider over abuses an API by making, say, a million calls every minute, then the API will become slow and unstable for everyone else. This is a developer authenticating themselves with the API. On the other hand, you also have authentication from the user of the app. This is when a user allows access to their own personal data on a service. Consider MyApiApp. With this, we will be asking permission from a user to access their own personal newsfeed.

To make users less wary about giving their personal data to an application, there are different types of authentication that can be done:

HTTP Basic Access Authentication. This is a very basic form of authentication since it only requires a username and password. This is transmitted in the header of the HTTP request. This is the worst kind of Authentication, as the user data is only weakly encoded, offers no encryption, and therefore offers only a minimum of security.

OAuth 1.0. This method provides a greater degree of security and works with things called tokens. A token is a unique string that can be assigned to an individual user. For example, MyApiApp can request a token from the user through the form of a Facebook login button. From there, the MyApiApp will then be able to use this user token to access the allowed uses of the Facebook profile. To the user, this process would very much look like downloading an app from the Android App store, where a list of permissions the app requires is provided. Due to the complexity of OAuth 1, most services rely on OAuth 2 in the meantime.

OAuth 2.0. OAuth 2.0 is more than just a simple upgrade to OAuth 1.0. It is in fact a new protocol, that operates in a completely new way. The main goals of OAuth 2.0 were to improve interoperability, as well as safety. That is, the new OAuth 2.0 protocol is able to used by many more different services (Interoperability), and the security of the protocol is a lot better and secure from attacks from the OAuth 1.0 protocol, mainly because of reduced complexity and the use of well known and tested standards.

Starting to add APIs to your application

Before the implementation can start it is necessary to read the API documentation. This is your guide to what might be different or unexpected with the API.

When reading the documentation, you want to make sure that you find the answer to these four questions:

• What kind of API is it? (RESTful, SOAP, JavaScript or XML-RCP)
• What data format is used in the request? (JSON, HTML or XML)
• What kind of authorization is used / required? (OAuth 1.0, OAuth 2.0, HTTP Basic Authentication)
• What functions are available for me as a developer?

Once all of of these issues are resolved, you will then be able to start including your API into your application.

The Easier Way for Beginners to add APIs

With all of these things to do, adding an API to an application can be pretty complicated for beginners. Additionally, in coding, sometimes time is of the essence. You want market penetration before your competitors. It is for these reasons, as well as the complexities of integrating APIs as listed above, that we have created the CloudRail Universal API. The way the CloudRail Universal API works is a lot simpler than all of the above:

CloudRail offers you a simplified API and handles most of the OAuth authentication flow for you. Moreover it speeds up your development because the solution let’s you integrate multiple services via the same unified API. If you are new to APIs CloudRail is the right way to start. There is absolutely no reason to go the complicated way first. And don’t worry, CloudRail is completely free to use. Lern more about the solution here.

If the above seems a little too complicated for you, do give CloudRail a try!

This article was provided for us by Jonas, a student of computer science currently working with CloudRail as an Intern as part of the CloudRail internship program

Reference Link: https://blog.cloudrail.com/api-tutorial-for-beginners/