Month: June 2021

Build a mock REST API with Swagger UI using OPEN API Specification and Docker.

Posted on by dev_nuvolar

In this article, we are going to build a mock API using OpenAPI specification (OAS) and a Swagger UI in order to expose the API through a user interface directly. The entire implementation will be carried out using OpenAPI specification and a bit of docker, so no programming language is needed in order to have your API fully operational.

Written by: Gerard Auguets, Senior Software Engineer at Nuvolar

Requirements

Docker & Compose:

VsCode (Optional but recommended):

Some knowledge about REST APIs.

Please find our example repository with a completely functional implementation below. You can use it as a guide during the tutorial:

What is OpenAPI?

Imagine a software project that involves different teams (Front end, Backend, Devops). Usually, these projects start in parallel and all parties depend on the work of the rest of the teams. For example, a Single Page Application that needs to make queries to an API in order to get information from different users.

Firstly, all the system requirements must be defined properly, such as the different functionalities, the information across different systems, and so on. To meet all the expectations, the Backend Team will develop an API in order to interact with the storage systems and provide the necessary information to the Front end. At the same time, the Front end team will develop the User Interface and all of the user interactions.

To optimize development time, the Front End needs to know the API to which it will consult the information, what type of data and responses it will obtain, among other things. But what if the API development takes longer than Front End development itself?

That’s where the OpenAPI specification comes into play. An OpenAPI file allows you to fully describe your API, including:

  • Available endpoints (/users) and operations on each endpoint (GET /users, POST /users).
  • Operation parameters; Input and output for each operation.
  • Authentication methods.
  • Contact information, license, terms of use, and other information.

Basically, all of the information that third party systems need to interact with an API and thus start the integration phase, even if the backend development is not complete.

This is not only useful for Front End teams, but also for Backend developers as it will serve as a guide for the development of the final API.

What is Swagger?

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs.

In this tutorial, we will focus only on Swagger UI, an interactive API documentation that helps users interact directly with APIs through the browser and retrieve mock data for development purposes.

Steps

  1. Build an OpenAPI specification file in order to define the API and its structure.
  2. Build the mock server using the OpenAPI specification file.
  3. Expose the OpenAPI specification through Swagger UI and connect it directly to the mock server in order to fetch already defined mock data.
  4. Build a compose file in order to orchestrate all the services and enable the project setup in a few steps.

1.Build an OpenAPI File API

Firstly, we need to develop our first API using OpenAPI specification. To do so, we can use an online editor, such as Swagger Editor by Swagger https://swagger.io/tools/swaggerhub/. This tool allows you to design, describe, and document your API in an online open-source environment.

As an alternative, we can use other options such as our IDE. In this case, VScode provides support to OpenAPI files, allowing us to preview the content and the rendering of the file through the IDE.

In this tutorial, we’ll use VSCode so that we’ll be able to split our OpenAPI specification file into different files and organize our API better.

Remember, the goal of this tutorial is not to go into how OpenAPI files are created in detail (although we will do a recap), but to understand how to integrate them with Swagger and create a mock server with them.

Now let’s create our first OpenAPI file!

First, open VSCode and create a new host folder. We are going to place all related files inside of this folder. Once created, we need to create a new json file. You can call it anything you want, but for simplicity, we’ll call it swagger.json. This file will contain all the OpenAPI specifications.

To work more efficiently, we’ll create different files to split the specification code. This will help to organize our API in blocks rather than having one single large file. The structure that we need will look like this:

As we can see in the previous image, the swagger.json file will orchestrate the entire OpenAPI specification. However, the rest of the files are also part of the documentation? and will contain code related to their own title. All components defined outside swagger.json can be accessed by it using references. You can learn more about how OpenAPI specification files are organized here: https://swagger.io/specification/

Let’s dive in a bit more with the different files. It is recommended to analyze the different files downloaded from the repository while reading this section in order to obtain a better understanding of the solution. In this example, we decided to implement a small API to consult Aircrafts and Airports (let’s assume that our company is related to the aviation industry :P)

  • Swagger

This is the main file where the API configuration is defined andthe different paths and routes that the API will contain are displayed. Typically, all OpenAPI specification files can be declared in one single file. However, in this case we are using a different approach.

Let’s analyze the different labels:

  • Openapi: Indicates the version of the used specification
  • Info: Contains some meta information about the title, contact, and so on.
  • Servers: Indicates the servers that will provide the information to the swagger requests. (In this case, the mock server that we’ll build with the same file).
  • Tags: Name and description of the API resources.
  • Paths: All the paths and resources are defined here. All the resources with its verbs, parameters and responses should be defined here. You can take a look at the implementation in the repository, but for this tutorial, a basic example is provided.

The OpenAPI specification file could also be created using different Swagger editors or in a single file.The way the Swagger.json file is built is up to you.

  • Schemas

This file contains the different schemas that will be used in our API. All the objects and their types are defined here. Once defined, these schemas are used in the schema label under content label for each resource response. Schema Example:

  • Responses & Responses_examples

This file contains the responses for the different endpoints. Each response should contain at least one schema in order to provide the schema documentation for each resource when requested through the Swagger UI. It is highly recommended to provide at least one example (response_examples.json) to provide the mock server with real responses.

  • Parameters

All the parameters used in our API should be defined here. The name, location, description, schema, and other attributes should be defined for every parameter in order to be usable in our Swagger documentation.

2. Build the services (With docker compose)

In order to deploy our API, a compose file will be created. Compose is a tool used to define and run multi-container Docker applications. More information about compose is available here: https://docs.docker.com/compose/

This compose file will contain different services that will be in charge of carrying out different tasks:

  1. Validate and build a valid/final OpenAPI specification file built in the previous section. As references and multiple files are being used, a unique OpenAPI file must be created, gathering all the necessary information. This file must follow the requirements provided by OpenAPI specification (more on VSCode and OpenAPI). To do so, a docker service will be created in order to validate and build the final file that will be used to deploy the Mock server and the Swagger UI.
  2. Run and expose the Mock Server using the OpenAPI file generated in the step n. 1.
  3. Run and expose the Swagger UI using the OpenAPI file generated in the step n. 1.

In order to achieve all of the steps, our compose file will use different images pulled from the dockerhub created by 3rd parties.

Let’s build a compose file that contains the different services. You can find this version in the provided repository.

The entire file is provided below with comments in-line in order to explain in detail the functionality of each service.

This docker-compose file must be located in the same folder as the rest of the documents.

3. Deploy the solution

Once we have our OpenAPI specification file completed and all of the necessary services declared, it is time to run the services.

  1. Open a terminal
  2. cd into the directory that contains all the files, e.g:
  3. $cd your_folder_containing_all_files
  4. Execute the following command in order to run the compose file:
  5. Docker-compose up (add -d if you want to run it in detached mode)

After running the commands, you’ll see that all of the services have started.

As shown, the swagger_build label has created the schema.json file properly. Then, the mock server and the Swagger UI were built around that file, exposing the mock server to the port 8000 of localhost and the Swagger UI at port 80 or localhost. (Notice that the message says the mock server is on port 5000, but that only applies inside docker’s network).

4.Test it!

Open your browser and navigate to localhost:80/swagger, or just localhost/swagger, to check if the Swagger UI is working properly. You should see something like this:

Now you can make requests to the different endpoints and get real answers provided in the OpenAPI specification file, following all the requirements that you defined for your API.

Remember that you can use parameters, consult the schema of the responses and much more, allowing the frontenders to integrate development easily and without having the real API in production.

Notice that the Swagger UI is getting the data directly from the mock server (at localhost:8000). You can do regular HTTP requests directly to the mock server using services such as Postman, or by simply integrating the FE solution to get real information.

Here’s an example of a regular request to airports endpoint:

And that’s it! Every time a change is made to the specification, the compose file needs to be reloaded, stopping the service and repeating step 3.

Now you can define your APIs as well as offer and consult them without developing the final API! This will save a lot of time for both you and your teammates and increase the productivity of your team significantly!

Choosing the right technology partner will help you save time and money

Posted on by dev_nuvolar

Choosing the right technology partner will help you save time and money

Are you still wondering why your company needs a technology partner? Or maybe several? As we will explain below, technology partners streamline and make the digital transformation of companies less costly. In other words, removing the o need to create or maintain internal IT departments. This helps your business focus more resources and efforts on customer acquisition, customer loyalty, and business consolidation. Keep reading to learn about the importance and benefits of having good allies in the Keep reading to learn about the importance of having quality technology partners for your business.

What is a technology partner?

In principle, technology companies develop and offer technology as a service. These technologies could be related to IT solutions that facilitate internal processes (CRM, ERP, and other applications). Technology partners are also important for website development and online marketing management, providing expertise and strategies for SEO, SEM, and SMM. They also provide services linked to Internet connectivity and communication networks between computers and mobile devices.

The close relationship between your company and your technology or service providers is key. This relationship should not be limited to the supply and installation of solutions. It should go further with constant advice, monitoring of solutions, and continuous improvement of the products or solutions implemented… This is the difference between a technology supplier and a technology partner. A partner is dedicated to building valuable relationships with its customers and avoids acting just as a simple supplier. In other words, a true partner isn’t satisfied with just selling a product to your business, but rather focuses on the value they can also bring in terms of consulting, add-on services, and long-term support… In short, this is what defines a technology partner.

Advantages of having a good technology partner

Several reasons justify partnering with reliable technology companies. Specifically when your company is undergoing a digital transformation. Here is an overview of the advantages of having a good technology partner.

Allows a greater focus on the business mission.

Let’s assume that your company is a mass consumer retail business and your focus is on offering the widest variety of brands to customers. You also need to anticipate changes in buyer behavior and personalize your offers through customer segmentation. On the other hand, it is essential to improve your shipping services and provide customer support that increases their loyalty over time. The goal of all these business activities is to help meet your company’s organizational and financial objectives.

Digital applications play a vital role in these business activities, helping to automate and streamline repetitive processes. However, establishing an internal IT development department would mean investing time, talent, and resources which may be difficult to fit into business objectives.

Cost savings

To handle all of the business activities mentioned above successfully, we know there’s a need for cost savings when possible. However, setting up an entire IT department with web developers and network maintenance experts would mean a costly process of hiring qualified staff.

On the other hand, a partner like Nuvolar can provide your business with the technological solutions you need, customized to your business needs. With Nuvolar, you will have access to trained staff that can manage your projects and deliver a reliable development environment. Moreover, we can provide you with customized solutions and services on a pay-per-use basis. Having a technology partner under these conditions can save you from making significant investments in hardware and software infrastructures. It can also help to reduce maintenance costs and internal resources.

Optimize storage space and resources

Along with cost savings, having a technology partner with vast resources can help optimize storage space and cost. For example, a partner that provides reliable cloud computing will prevent you from investing in equipment that could become obsolete in a few years.

As your business grows, you will need to manage more data and resources in the cloud. Working with a partner that has experience with cloud operations can facilitate the management of websites, applications, and files without issues.

Everyday processing, storage, and design capabilities are improving and growing. Consequently, updating them to keep up with these changes is a big challenge. A technology partner like Nuvolar can help your company manage it all and grow with efficient, customized web solutions and applications.

Discovering and incorporating innovation: the role of a technology partner

Technology is evolving unstoppably, and investing time and resources in researching and incorporating new technology has become a tiresome and costly process. However, an experienced technology partner can help with the adoption of the appropriate technology that fits the digital infrastructure of your business better yet. Additionally, a digital partner can provide you with a truly objective view of the latest technology trends. This will ensure that your next investments in technology tools are truly going to help your company in the long term.

Nuvolar is your reliable technology partner

At Nuvolar, we understand the needs of digitizing your company’s processes to make them more efficient and profitable. We have over 12 years of experience developing customized and effective software. We bring together a multidisciplinary staff of highly talented professionals who are capable of understanding your business model and needs and creating intelligent tools that add value to your business.

Web development is our passion! We are dedicated and committed to the goal of making your project a success.

Our services include:

  • Design of customer management, sales, and marketing software for B2B and B2C companies. We also have experience creating solutions for logistics management, operations, and all business processes. Additionally, we address the integration of contact channels and customer support.
  • Management and development for product implementation.
  • Development with UX (user experience) and UI (user interface) design frameworks.
  • Consulting and post-implementation support.

Our development strategy uses Agile methodologies, allowing us to create software solutions adapted to your company on tight deadlines. Additionally, we continuously verify with you the performance and status of the project at each delivery stage.

At Nuvolar, we are specialists in Salesforce CRM customization as well, and we’ve helped many businesses develop Salesforce solutions. We have been certified Salesforce partners for over a decade and we have deep knowledge of Salesforce’s entire suite of offerings.

For all of these reasons, Nuvolar is the ideal technology partner for your business, so don’t hesitate to contact us!

How can cloud solutions improve the business of consumer goods?

Posted on by dev_nuvolar

How can cloud solutions improve the business of consumer goods?

The consumer goods industry is undergoing continuous and accelerated changes, much of which are supported by cloud solutions. In this sense, it could be said that the cloud plays a dual role, acting as a driver of evolution and at the same time generating responses to new market expectations.

There is no doubt that retail and mass consumption are no longer the same as they have always been. The constant innovation of mobile connections and sophisticated communication devices are revolutionizing the way we interact. At the same time, this interaction with online channels and especially social networks generates immense amounts of data. This information is used by the most digitized companies, thanks to technologies such as Big Data and advanced analytics.

To all this, we must add the constant globalization of value chains. Not to mention the emergence of new digital companies that are knowledgeable about technological tools, ready to take market shares from established companies. As we will see later, all these trends have common support: cloud solutions.

Customer-centric in the areas of retail and consumer goods

Today, cloud solutions are enabling consumer goods and retail companies to interact permanently with the consumer. Of course, we are talking about digitized consumers with access to mobile and fixed devices. Through these, they remain connected to the Internet, so they have constant access to information about products and brands. In addition, this connection allows them to learn about the experiences and opinions of other customers about the different products and services on the market. In both cases, they do so immediately, wherever they are, and in real-time.

These digitized customers use a variety of technologies and channels to communicate with each other and with the brands they consume. They also have a lot of information and usually have very well-defined what they expect from the supplier firms. At the same time, they have many product and service options, and, most importantly, they are no longer limited by the distance between them and the companies’ physical retail location.

In this context, it is very important that brands intensify their level of attention to consumers, which implies maintaining a constant interaction with them. In this regard, cloud solutions will be key to achieve three fundamental purposes:

  • Attract consumers with innovative products, services and/or added value.
  • Present contextualized and personalized offers that arouse the customer’s interest.
  • Obtain customers information through various channels and technologies and interpret it through advanced data analysis. This makes it easier to anticipate consumer expectations and make decisions accordingly.

Customization and context

Cloud computing supports all the technologies and solutions that allow us to know and understand the customer, considering their current situation and the factors that influence their decisions. These include their preferences, activities and recent purchases, as well as their geographic location and purchasing power. In this way, brands can present customers with personalized offers that are consistent with these factors at the right times.

For example, if your company has a geolocation service, you can send messages to customers who are close to your physical stores. You can include a personalized offer along with an invitation to visit the point of sale. Once there, you can suggest specific places in the store to find items of interest to them. On the other hand, through Big Data and advanced analytics you can study purchase history and consumption patterns, in order to anticipate changes in consumer behavior. For example, if the frequency of purchase decreases or increases, or if they consult opinions about other brands. With this information, it is easier to decide between offering incentives, modifying the offer or creating new products.

Increased customer knowledge

It’s nothing new for people to share brand opinions on their social media accounts. However, what is overwhelming is the number of consumers connected and the volume of data shared. For this reason, it is critical for companies to have the ability to capture, analyze and convert this data into valuable customer insights.

But these are not the only platforms for gaining customer insights about the brand.In addition, there are customer service channels, after-sales support, physical points of sale, ecommerce site and applications for requests and orders. Data from social media and other sources, available in the cloud, provide relevant insights about customer behavior.

In this sense, customer relationship management (CRM) is an essential tool for monitoring consumer interactions on social networks. Mainly in relation to the frequency and tone of the brand mentions and the level of satisfaction or rejection. As well as references to their experience as a consumer and the consequent recommendation (positive or negative). Without forgetting the other channels of interaction already mentioned and that involve more direct interaction with the customer, such as e-commerce and applications, which are more closely linked to online sales.

Cloud drives operations in retail and consumer goods companies

Another advantage provided by cloud solutions is to streamline the operations of consumer goods and retail companies. An example of this is the ERP or enterprise resource planning environments. In short, these systems make it possible to monitor the company’s end-to-end workflow. In this way, it is possible to visualize and obtain operational data from the supply chain, human activity, manufacturing, maintenance, finance and administration, in order to make them more efficient. Based on these objectives, such solutions employ technologies such as Artificial Intelligence, Machine Learning, and the Internet of Things, among others.

Even though integration between areas with the same system is ideal, the scalability of cloud solutions allows for the gradual incorporation of applications. Hence, the diversity of these tools:

  • Supply Chain Management (SCM). As the name suggests, this solution integrates the planning and execution of processes more effectively. This includes material flow, production, inventory management, logistics, fleet management, and warehouse operations.
  • Human capital management (HCM). HR software automates tasks such as profit management, payroll, and scheduling, among others. They usually include modules for performance evaluation, hiring, and professional training.
  • Online sales. In this case, the e-commerce module allows visualization of the catalog, inventory, price changes, and the supply chain. These aspects will influence customer offers and, to a greater extent, marketing campaigns. In addition, ERP applications for e-commerce are adaptable to different types of business: B2B, B2C, or C2C.

How can Nuvolar help your retail or consumer goods company?

After this brief summary of the contributions of cloud solutions to consumer goods and retail organizations, we want to tell you how Nuvolar can help you achieve your company’s goals. We are dedicated to developing web solutions and custom applications for companies specialized in manufacturing and/or mass marketing of products to the final consumer, whether food, beverages, personal care, beauty, cleaning products, or clothing.

More specifically, we specialize in the design, development, and implementation of software and digital solutions for companies. For that purpose, we use UX (user experience) and UI (user interface) design methodologies. Our multidisciplinary staff of accredited professionals has the knowledge and skills necessary to understand your business needs and bring your ideas to life.

In Nuvolar we are able to customize the Salesforce CRM to the business model, industry, characteristics, and needs of your company. This way, you will not miss anything they say about your brand. By decanting and analyzing this information, you will obtain relevant insights to know your customers and make the right decisions. Indeed, we have authorized Salesforce partners, on whose platform we have been developing our applications for more than ten years.

Contact us and you will know why we are your best choice in cloud solutions!