API (Application Program Interface)

 

WHAT IS AN API?

An Application Program Interface (API) is a set of routines and patterns established and documented about an application or system. Companies release this information so that other applications can use its functionality without needing to install the software.

In other words, an API is a set of information (programmable codes) that allows applications to communicate with each other more transparently. It is the interoperability – the possibility for applications and users to communicate.

For that to happen, the development of the APIs happen through two different elements:

• A specification that describes how the information – or data – can be exchanged between programs.
• An interface software that is written specifically for this purpose and published so the users and clients can access it.

Thus, the software that wants to access the features and capacities of an API is named “call”. The software that creates and gives access to its APIs is called “publish”. 

WHAT THE API SOLVE AND WHY IS IT IMPORTANT?

Basically, there are three main types of API:

• Local
• Web-based
• Program based

But, what do they solve and why are they so important nowadays? It is easy to find software and applications that previously were developed to do specific things and that, today, already have APIs that allow them to have different functions. This reduces the developing time and decreases the possibilities of errors. 

Besides that, the APIs also helped to enhance the quality of the software in the last decade. That happened mainly because of the growing number of cloud-based applications. This development encouraged companies to use more APIs and different systems began to communicate more, exchanging more information. All that made the user experience better not only for final-users but also for managers and decision-makers.

TM Forum standard

One important thing that all companies must know and follow is the TM Forum standard. It is an international guidebook of rules and best practices to organize APIs and other frameworks.

The TM Forum is a global industry association for service providers and suppliers in the telecommunications segment created in 1998 to solve system and operational management issues. Through an open and collaborative environment, the Forum has over 850 member companies.

The organizations that follow the TM Forum standards have some important benefits, such as:

• Market recognition
• Reduced cost of applications integration
• Reduced risk in transformation projects
• IT architecture simplification and agility
• And much more!

THE REST CONCEPT

REST is an acronym for Representational State Transfer and it consists of some principles, rules, and constraints that, when followed correctly, can allow the development of a project with well-defined interfaces.

Described by Roy Fielding – one of the main creators of the HTTP protocol – in his doctoral thesis, REST is a model to be used in the architecture projection of distributed software based on network communication. 

But, what does that mean? By following the rest principles, applications and software are built in a manner that makes it easier for them to communicate. And, therefore, build well-defined APIs.

So, we can say that REST is one kind of architecture and communication model that is mostly used in the development of web services. Thus, with the growth of cloud services, REST has been the main and most logical choice to create and build APIs that allow users to connect and interact with other applications and software. 

Stateless Communication: what is that?

As seen before, the main system that uses the REST model is the web. We all know that today the internet has billions of clients connected to it, exchanging information and data all the time. But, what makes it possible for the web to manage this huge amount of users and information without crashing and with such a good performance and scalability?

The answer to this question is stateless communication. This principle means that all requisitions made by a client through a REST service must contain all the necessary information for the server to understand and execute them correctly.

Therefore, any state data must be maintained by the client and not the server. The client must not depend on any information previously stored in the server to process a requisition. That is what makes it possible to enhance the REST service scalability and reduce the need for a whole amount of physical resources to store data.

HOW TO USE THE APIs

It is known that all applications manage information and data. For example, a telecommunications application handles its users, technologies, pieces of equipment and so on. All those things are called resources in the REST model.

So, a resource can be defined as the type of information that this application manages and, following the REST model, each one must have a unique identification. This ID is used so that the application can differentiate which of the resources must be manipulated in a request.

To do that, the resource identification follows the Uniform Resource Identifier (URI) concept. This notion is one of the standards used on the web and they are the interface for using your application services. They act as a contract for your users to access your system. 

But how does that work?

All the resources can be manipulated in many ways: you can create, update, delete and make many other operations with them. To do that, one of the most used models is the HTTP protocol. 

When a client sends an HTTP request for a service, besides the URI, it is important that they also assign which resources he wants to change and the type of manipulation he wishes to make. All this information comes with the HTTP protocol and each one of the manipulation methods, or verbs, has its own meaning:

• Get: obtain data from a resource.
• Post: create a new resource.
• Put: replace data from a resource.
• Patch: partially update a resource.
• Delete: delete a resource.

Examples

Let’s imagine a resource named Client to see how the HTTP methods in a REST service can be used:

Method	URI	Use
GET	/clients	Recover all clients data
GET	/clients/id	Recover a specific client data
POST	/clients	Create a new client
PUT	/clients/id	Update a specific client data
DELETE	/clients/id	Delete a specific client

USING THE HTTP CODES

In the HTTP protocol, all clients’ requisitions must result in an answer with an HTTP code. This code is used to inform the client if his request was successful or not.

There are several HTTP codes, each one with its specific semantic. So, they must be used wisely and in the right manner to let the user know exactly what happened to their request. 

The HTTP codes are grouped in classes:

• 2xx class: indicates the request was successfully processed.
• 3xx class: indicates that an action must be taken to complete the request.
• 4xx class: indicates the client caused an error in the request.
• 5xx class: indicates the request was not completed because of an error in the server.

 

Also, there are the main HTTP codes. It is important to know when and how to use them. Take a look:

Code	Description	When to use
200	OK	GET, PUT and DELETE requests executed successfully.
201	Created	POST requests when a new resource is created successfully.
206	Partial Content	GET requests that return only a part of a resource’s content.
302	Found	Requests made to old URIs that have been altered.
400	Bad Request	Requests that have invalid information sent by the client.
401	Unauthorized	Requests that need authentication, but the user data was not provided.
403	Forbidden	Requests that the client does not have permission to access the resource.
404	Not Found	Requests where the resource URI is invalid.
405	Method Not Allowed	Requests that have the HTTP method indicated by the client not supported.
406	Not Acceptable	Requests that have unsupported format solicited by the client.
415	Unsupported Media Type	Requests that have unsupported format sent by the client.
429	Too Many Requests	When the service has a limit of requests for each client and this number has already been reached.
500	Internal Server Error	Requests where there was a server error.
503	Service Unavailable	Request made to a service that is down for service or overload.

BWTECH’S EXTERNAL API

Knowing the importance of having a service that is not only portable but that can interoperate with other applications, Bwtech developed its own External APIs. Following TM Forum standards and the REST concept model, the feature was created to allow clients to integrate NetChart’s data with other programs they use in their daily routines.

With that, we are able to expand not only the knowledge gathered throughout the time but also the reach of all the intelligence that is inside NetChart and its modules.

To do that, the NetChart’s APIs created have the goal to let users search and use the following data to communicate with other programs:

• All KPIs registered in the NetChart database.
• All objects inserted in the database by element or technology.
• All PM charts that are available in the database by technology.
• All CM charts that are available in the database by technology.
• All PM and CM chart columns inserted in NetChart’s database.
• All KPI values that are available in the system.
• Raw PM and CM data by element or time frame.

ROUTES

As mentioned before, Bwtech’s API feature was developed following the TM Forum’s recommendations and best practices. Therefore, all of its route names keep an international standard. The implemented ones are listed below:

URL	Description	Request Method
/api/object/{tech}/Elements	Return all objects which can be used as arguments (filter by TECH).	GET
/api/object/{tech}/Elements/{elementType}	Return all objects which can be used as arguments (filter by TECH and ELEMENT_TYPE).	GET
/api/kpi/{tech}/Kpis	Return all KPIs which can be used as arguments. The KPI_ID accepts wildcards like % (filter by TECH).	GET
/api/kpi/{tech}/Kpis/{id}	Return all information of a selected KPI (filter by TECH and KPI).	GET
/api/tables/Pm/{tech}	Return all PM table names which can be used as arguments (filter by TECH).	GET
/api/tables/Cm/{tech}	Return all CM table names which can be used as arguments (filter by TECH).	GET
/api/tables/Pm/{tech}/{name}	Return the required fields from the desired PM table (filter by TECH and TABLE).	GET
/api/tables/Pm/{tech}/{name}	Return the required fields from the desired CM table (filter by TECH and TABLE).	GET
/api/kpi/{tech}/Kpis/{id}	Return KPI values for the desired elements and time frame (filter by TECH and KPI).	POST
/api/tables/Cm/{tech}/data/{table}	Return raw CM data for the desired elements and time frame (filter by TECH and TABLE).	GET
/api/tables/Pm/{tech}/data/{table}	Return raw PM data for the desired elements and time frame (filter by TECH and TABLE).	GET
/account/login	Return authentication token.	POST

SWAGGER

Swagger is a documentation website. It allows users to visualize and interact with your application API’s resources without having any of the implementation logic in place. With automatic updates, Swagger has tools that ensure that the API documentation available there is always up-to-date. Therefore, it is called live documentation.

Through the site, the user can find all the available API routes (with details of what they are and what they will receive) and a description of all the data that can be interoperated between the systems, allowing them to communicate.

 

How to use

In the Select a spec option, you can choose the context you desire to see.

The first spec to use must be the Auth API – v1 because through it the user can request his access to retrieve the APIs. This is the only route that is open, all the other ones need an authorization token.

Through the /account/login route, you can request the Bearer Token to access the other routes. To do that, you must give two main pieces of information: username and password.

After sending the information, the system validates it and, if you have authorized access, you receive the Bearer Token. 

With the token, go to the desired spec to request the APIs you need. Let’s imagine you want a KPI API.

1 – Select the KPI API – v1 spec.

2 – In the KPI page, you will find the routes available and models.

3 – In the model option, you can see all the information and data you’ll receive when requesting the API.

4 – When clicking on the routes, you’ll find their details: the HTTP protocol verb, what are the required fields and a model of response.

5 – Select the route you want and click on the Try it out button.

6 – Fill the required fields.

7 – Click on Execute.

8 – And the system will give you the Curl and the Request URL.

9 – Now you can copy the route with all the required fields already completed!