1. Introduction #
APIQuality is a tool that allows you to implement the entire API First lifecycle successfully and efficiently.
This document explains the steps to follow for the correct use of the tool. The main sections to be covered are the following:
- Registration.
- Login.
- Organization configuration.
- API Collections.
- Import APIs into the tool.
- API First cycle management of an API.
- Reports by Collections.
- Reports by Organizations.
2. Registration #
In order to use the tool it is necessary to be registered in it. To do so, access the URL https://app.apiquality.es/user/signin, where you will see a screen like the following one:
To create an account, click on the Register for free button, where a form will be displayed for you to fill in.
In order to register, it is necessary to accept the privacy policy and fill in all the required information.
Once the request has been sent and processed, you will receive an account verification email. It is important to note that if you do not verify your email address, you will not be able to start using APIQuality.
3. Login #
Once you have registered and verified your e-mail address, you will be able to access APIQuality.
We will introduce the e-mail with which we registered and the password we registered.
4. Organization #
Everything within APIQuality revolves around an entity called «organization». That is why, within APIQuality, we will find a series of configurable parameters that will allow us to operate later on our APIs (API Managers, style guides, etc.) within the same organization.
Once you register, an organization is automatically created, although more organizations can be added later and another user can add you to theirs.
In the field that appears in the header of the web you can see in which organization the user is and by clicking on this field, it is displayed. In this dropdown you can change the organization by clicking on another one of those that appear.
A new organization can also be created in the same drop-down menu by clicking on «Create organization».
A modal will open, in which we will be asked to enter a name for our organization and we will create it.
5. Config #
In the web header there is a «gear» icon and clicking on it displays a menu with the different screens that can be accessed.
5.1. General #
From configuration you can access «General» where the name of the organization you are in appears. The name of the organization is created when registering and can be edited from this screen.
In this screen you can also choose if you want to show the URL of the repository and the Mock Server. To do this, the checkbox must be selected or not and then save the selected. We must take into account that by default they are active, they will be reflected in section 6.2.2.
Finally, it indicates the procedure to delete an organization, providing the APIQuality support email (support@apiquality.io).
5.2 Adding members #
We can add members to our organization whether or not they have previously registered in APIQuality. To these members you must add a role or several roles and a collection or several collections to which you want them to have access, which is essential to be able to finalize the form. With each of the different roles the member will be able to perform different actions…
When you add a registered member you will receive an email informing you that you have been added to an organization.
When adding an unregistered member, he/she will receive an email to register and then another one to verify the account. In the members screen the status will change as the member registers and verifies.
In addition, members can be edited as well as deleted if necessary.
5.3 Import API Template #
An organization can upload one or more corporate templates so that its developers can access it when defining their APIs and uploading them to the tool.
To do this, the «API template» screen can be accessed from the configuration menu. Clicking on «Add API template» will open a form and clicking on the Select file button will load the definition file, provided that it has a .yaml, .yml or .json extension. This file can be downloaded or deleted.
5.4 Style guide #
Style guides are the set of rules that apply to the scanning of APIs.
By default, a style guide is created with the name of the organization that is used by default in all the collections we create that do not have a specific style guide linked to them. However, you can add as many style guides as you want to your organization. All style guides will have all rules enabled by default.
To create more style guides, access this screen from the configuration menu and click on the Create Style Guide button.
Within the creation dialog, we will be asked to enter a name for the style guide and to check if we want this new guide to be used by default in case we do not link any to the API collections.
If everything went well, the following message is displayed:
If we need to make changes to a style guide, we can modify it by clicking on the pencil icon or delete it by clicking on the trash can icon:
5.4.1. Style guide rules #
The style guide rules analyze API definitions, ensuring that they follow specific standards and best practices, guaranteeing correct functionality and consistency.
You can display the rules belonging to a particular style guide by clicking on its name.
From this screen, you can configure the rules that will be used to scan an API with the selected style guide, modify the parameter values in those rules that allow it, etc.
We can activate and deactivate as many rules as we want, taking into account that only those that are active can be edited.
In the editing dialog, we can modify the severity of the rule, as well as the associated parameters. Once the necessary changes have been made, click on Edit rule to save.
5.5 Collections #
Collections are a way of grouping APIs that allows working in a simpler way. It is important to take into account that style guides are applied on a collection, so all APIs belonging to the same collection will be scanned with the same style guide.
«Collections» can be accessed from the configuration menu. You can create as many collections as you want and in each of them you can add all the necessary APIs.
Once you access «Collections» from the configuration menu, you will see a list of existing collections, the number of APIs contained in the collection, the style guide, the ratings of the collection and a button to create a new collection. We can also edit, update and delete the desired collection.
It should be noted that once the registration is done and an account with its corresponding organization is created, a collection is also created by default, so when accessing «Collections» for the first time, the first one created by default will appear.
5.5.1. Create a new collection #
To start creating new collections click on the New Collection button.
Once clicked, a form will open where we will be asked to enter a name (mandatory) and select the style guide that will be applied in the API scan, as well as a description section of the same. It is important to remember that, if no style guide is selected, the one we have marked as default will be applied.
5.5.1. Colection detail #
Each of the created collections can be edited or deleted from the icons that appear to the right of each collection. Note that a collection that is associated to an API cannot be deleted.
The style guide associated with each collection created can be accessed from the style guide link.
You can also access the details of a collection by clicking on the link of that collection.
In the detail of each collection you can see all the APIs that belong to it and you can also create more by clicking on the Import API button although, as we will see in section 6, you can also do it from the API Explorer.
5.5.2. Colection report #
Once at least one API has been uploaded into the collection and the API First cycle has been run, a collection report will be generated, showing both the overall collection scores and the individual scores for each API.
The complete report with more information can be accessed in each API section. Section 6.2.2.1.
It should be noted that until we have assigned an API to our collection, we will not be able to have a collection report.
5.6 Branches and pipelines #
The «Branches and pipelines» screen can be accessed from the configuration menu. Here we can modify the API First cycle both in development and in production, although we must take into account that in production we can only modify the API Manager we want to deploy with.
5.6.1 Edit branche #
To edit or modify the API First cycle in the development environment, click on the edit icon, which will take you to the branch edit view.
In this view, we see the stages available for inclusion in the API First cycle, these tools are grouped by categories. Each tool can be added to the cycle, removed from the cycle, edited and in the cases of Microcks, Sonarqube and Newman it will be possible to activate or deactivate the score that is calculated. This score, if enabled, will be part of the score we calculate for the API.
5.6.1.1 Edit pipeline #
Within each branch, we can edit the pipeline to be executed. To do this we have to click on the API First Cycle button.
A text editor will open with the current yaml of the pipeline that we can modify. Once modified, we click on save the changes made.
5.6.1.2 Edit stage #
In addition to editing the pipeline, each stage can be modified by clicking on «Edit stage» in the configuration menu. Editing will open a text editor to modify the yaml to be executed.
5.6.1.3 Add stage #
In the development environment new stages can be added according to the needs of the organization. we will place name and description of the stage and we will write in the text editor the yml code of the customized stage.
5.7 Accounts #
The «Accounts» screen can be accessed from the configuration menu.
In this section, on the one hand, applications can be linked to integrate them in API Quality and on the other hand, repositories can be linked to import APIs from them.
5.7.1 Applications #
The applications that can be linked are GitLab on Premise, SonarQube and Microcks.
Please note that to link GitLab on Premise you must not have any API imported into your organization.
In addition, it is recommended to first link GitLab on Premise and then SonarQube and Microcks for the correct functioning of the application.
To make the linking we must fill in the form with the required data, which are mandatory.
5.7.2 Repositories #
For the linking with the repositories: Gitlab, Github, Azure Devops and Bitbucker. to upload APIs from them, click on the link button.
We can perform the linking in two ways for Gitlab, Github and Azure Devops repositories: via browser login and via personal access token.
On the other hand, in BitBucket we will only find the option of linking by means of a browser login.
5.8 API Managers #
The «API Manager» screen can be accessed from the configuration menu.
In this section you can configure those API Managers in which we later want to deploy our APIs. Apigee, Azure API Management, Mulesoft, AWS API Gateway, Kong and WSO2 are the API Managers available for linking.
Clicking on the link button will open a window in which we will be asked for the access information for each of them.
5.8.1 Apigee #
To configure the Apigee API Manager, click on the link button.
Once clicked, a form opens where the fields Username, password and apigee organization must be filled in. In this case, all three fields are mandatory in order to click on the link button and finish the process.
Once the API Manager is linked, the linkage can be edited or removed from these icons.
5.8.2 Azure API Management #
To configure the API Manager Azure API Management click on the link button.
Once clicked, a form opens where, in this case, there are two ways to link.
First of all, if you choose the option «Login in browser» you will be redirected to the Azure website to login. Once you have logged into the API Quality website, you must finish linking by filling in the Azure instance name field.
The second option to link is to choose «Login via primary key» and fill in all the mandatory fields that appear with this option which are subscription ID, group name, identifier, API key and URL.
Once the APImanager is linked, the linkage can be edited or removed from these icons.
5.8.3 Mulesoft #
To configure the Mulesoft API Manager click on the link button.
Once clicked, a form opens where the Mulesoft authentication type and Mulesoft organization fields must be filled in. Once the authentication type field is filled in, two more fields appear to be filled in. Depending on what has been chosen, the user name or Client ID must be filled in. The second field to fill in is the password.
In this case, all fields are mandatory in order to be able to click on the link button and finish the process.
Once the API manager is linked, the linkage can be edited or removed from these icons.
5.8.4 AWS API Gateway #
To configure the API manager AWS API Gateway, click on the link button.
Once clicked, a form opens where the AWS ID and AWS Access Key fields must be filled in. In this case, both fields are mandatory to be able to click on the link button and finish the process.
Once the API Manager is linked, the linkage can be edited or removed from these icons.
5.8.5 Kong #
To configure API Manager Kong click on the link button.
If you choose default, no more fields will be displayed.
Once clicked, a form opens where you must fill in the Kong authentication type and URL fields, both of which are mandatory. Depending on the type of authentication chosen, more fields will be displayed.
In the case of choosing JwtAuth you have to fill in the fields algorithm ,jwt key and URL the fields are mandatory to be able to click on the link button and finish the process.
If you choose KeyAuth you must fill in the API key field which is mandatory to be able to click on the link button and finish the process.
In the case of choosing Oauth2 credentials the Client ID, provision key, client secret and scope fields will appear. All of them are mandatory in order to click on the link button and finish the process.
And finally, if BasicAuth is chosen, the user name and password fields must be filled in before clicking on the link button to finish the process.
Once the API Manager is linked, the linkage can be edited or removed from these icons.
5.8.6 WSO2 #
To configure the WSO2 API Manager, click on the link button.
Once clicked, a form opens where the user name, password and URL fields must be filled in. In this case, all three fields are mandatory in order to click on the link button and finish the process.
Once the API Manager is linked, the linkage can be edited or removed from these icons.
Once we have linked the API Manager(s) we want to use to deploy your organization’s APIs, we display all the URLs of the API Managers.
5.9 Developer portal #
The «Developer portal» screen can be accessed from the configuration menu.
When accessing this screen, two tabs appear which redirect to the «Environment» and «Developer portal» subscreens.
5.9.1. Enviroment #
The «Environment» screen is the one that appears by default when accessing the developer portal.
If no environment has been added yet, you should see a message indicating this and the add environment button in the center of the screen.
Once you click on add environment a form opens where firstly you have to choose whether the environment is to be linked by primary key or by token. Secondly, there are two dropdowns to choose the API Manager and the environment. And finally, you must fill in the form fields, which will change depending on the binding method previously chosen.
5.9.1. Developer portal #
The «Developer portal» screen is the second tab when accessed from the menu. Clicking on the tab takes you to this screen.
If no developer portal has been added yet, you should see a message indicating this and the add developer portal button in the center of the screen.
It is important to note that in order to add a developer portal you must have previously created an environment since one of the fields to fill in the form is to choose one of the created environments.
Once you click on add environment a form opens where firstly you have to choose between two options: create new developer portal or link existing developer portal. Secondly, the drop-down field «environment» appears to choose one of the created environments. And finally, you must fill in the form fields, which will change depending on the previously chosen way of adding a developer.
6. APIs Explorer #
The API Explorer is the main screen that appears once the application is accessed and it is the one that belongs to the home icon.
In this screen you can see a list of all the APIs that have been imported into the organization where you are, regardless of the collection to which they belong.
In the list you can use the search engine and filters to search more easily for one of the APIs.
In addition, in each of the APIs there are icons with which you can access the API details, update the api or delete it.
6.1. API import #
In order to import an api you must click on the Import API button at the top right.
Once the button is clicked, a form should open with the following fields:
- Name of the API to import
- Collection where to save the API: If one is not selected it will take the one we have defined by default).
- Tags : You can create your tags by entering a name and then clicking on Create.
Import method which can be:
- Through a local file where a button will appear to select a file. (.json, .yaml, .iml, .yml)
- URL where a field must be filled in with the desired url (in raw format, it must be a public URL).
- Through gitlab, github, bitbucker or azure repository. The repositories will only be available if we have linked an account from «Settings».
- Using corporate style guide. It will only be available if an api template has been previously imported.
- By standard definition where you can choose between Open telco and Open Banking and within this you must choose between Open Data API – ATM Locator, Read/Write API – Account and Transaction or Open Data API – Branch Locator.
Once the data has been entered by clicking on the Import Api button, the configuration is saved. If everything has been successful, a success message should be displayed. If an error occurs, an error message should be displayed clearly indicating the error.
6.2. API information #
In the «API Explorer» screen, each of the APIs in the table has an eye icon. By clicking on this icon you can access the API information.
Once this screen is accessed, two sections can be observed:
Firstly, «API First Cycle» appears where, as the name suggests, the API first cycle can be monitored. Secondly, there is the «General information» section.
In this section there is a drop-down menu to choose the branch where the development and main options appear.
6.2.1 API First cycle #
Being in the development branch, to perform the testing of our API, we have enabled the following sections:
6.2.1.1 Definition quality – sonarqube: #
In this section we can visualize the definition file associated to the API, as well as the qualification of our API.
By accessing the menu, we can run , update as well as edit the API definition. We will have the option to rescan the API in case we have made modifications in the definition, as well as to visualize the errors and vulnerabilities within the file itself to have a clearer view of the problem.
We will be able to make modifications in the definition of our API directly to save it later, to do this we must access the «Definition» section.
In the hamburger icon we have different options, such as hide error details, download option, upload a file for update (it has a drop-down with two options: local file or URL), show swagger view, show editor view.
If we select «Editor» view we can edit the file more comfortably in the tool itself and save these changes:
If we select Swagger view:
In the Swagger view, the rules that we have defined in our style guide and that have not been fulfilled will be displayed. Clicking on the name of the rule will open a view with an explanation of the selected rule with an example of correct and incorrect compilation.
On the other hand, in case we want to replace the file, we can click on the «Upload file» button, where the following dialog will be opened to choose the import source.
We also have the possibility to download the current API file using the «Download» option. This is useful in case you have edited the definition from API Quality, and you want to have a local copy with the last changes made.
6.2.1.2 Mock server – microcks #
A drop-down can be displayed with the index and score classification.
We can launch our stage as well as update it.
Clicking on the URL redirects us to the microcks page.
6.2.1.3 Contract tests – swagger2postman #
Allows to generate postman collections for testing purposes.
In this section we can generate our Postman collections. To do so, click on the Configuration button and then on Generate collections.
When you click on it, a dialog will open where we will be asked, with the required fields, first, to name the Host we want to generate, then the Port. Then we also have the option to generate these read-only endpoints, and finally click on the create button.
Once the collections have been generated, we will have the option to download them by clicking on the Download Collections button. If desired, an environment can also be edited.
6.2.1.4 Quality tests – newman #
Performs tests based on a collection of postman.
To finish the testing cycle of our API, we must click on configuration and we have available the section Quality Tests – «newman».
To run a test, click on the Run test button.
Next, a dialog will open where we will have to include the json file of the Postman collection to examine, as well as the environment file associated to it to perform the test, once uploaded we will be able to launch it and update it,
:
Once the report is generated, a view like the following one will be displayed to examine the results:
6.2.1.5 Microservices #
APIQuality allows you to generate the archetype corresponding to the imported definition in a specific language. This microservice will be available in the API definition repository.
To generate the archetype, we will have to choose among the languages available in the tool, currently Java Spring Boot or C#. NET, and click on the Generate button. It is important that the definition contains the correct structure so that the archetype can be generated; otherwise, an error will be returned.
To do this, click on configuration, it will take us to a section where we can select in which language we want to use the following language:
Once the archetype has been generated, the Download button will be enabled, which allows you to have a local copy of the base project.
6.2.1.6 Deployment in Api Manager – kong, Deployment in Api Manager – mulesoft, Deployment in Api Manager – wso2:v4, Deployment in Api Manager – wso2:v3, Deployment in Api Manager – aws #
The last section of the API First cycle is the deployment. To deploy an API we will choose the API Manager in which we want to deploy it, click on the menu, the option «Execute stage» will be displayed for its deployment.
To deploy an API, click on the Deploy API button:
This will open a dialog where we will have to select the API Manager, depending on the one we choose other options will be displayed where we want to deploy our API. We will also display Backend service URL, which is not mandatory.
Once deployed, we will start to see the status of our API.
Clicking on the delete icon will open a dialog to confirm that you want to delete the displayed API.
When trying to deploy an API you must take into account that only those API Managers previously configured will be available.
6.2.1.7 Developer portals #
In this section we will be able to publish our API, which we have already configured previously, as described in point 5.9.
6.2.2 General information #
Secondly, there is the «General Information» section.
The «Report» screen can be accessed by clicking on the blue icon to the right of the title or on the «Report» link. The report can also be accessed from the «Rating» option, with the link to the report.
An overview of the API can be found here.
You can change the API version. Clicking on this field opens a drop-down to choose another version or create a new one.
You can also add and create new tags, explained in the point.
Finally, the sections where the links to our «Mock Server», «Documentation» and «Definition Repository» APIs are located appear, if they have not been deactivated as explained in point 5.1. We can see the «Lines», «Schemas», «Routes» as well as «Number of operations» of the scanned API.
6.2.2.1 Rating #
We can access our API report which contains its global score and a score for each of the tools we have configured. We can also see general API information such as the number of lines, schemes, routes and operations. We have a link with information about our notes/grades.
In case they exist, in the «Definition» section we will find a list of the definition errors and vulnerabilities that our API contains based on the style guide.
6.2.2.2 APIs versions #
To view or modify the versioning of our APIs, we must access the drop-down menu and modify our version taking into account the nomenclature, otherwise we will get an error.
7. My profile #
You can access «My profile» from the icon that appears at the top right in the shape of a person’s profile, which allows you to access your profile as well as the option to log out.
Once we access the option «My profile» in this screen on one side we can find the personal data such as name, surname or language. These three fields can be edited where in the case of the name and surname you can change the desired data in this field and in the case of the language with the drop-down menu you can choose Spanish or English. To save these changes always click on Save changes.
On the other hand, there are the access data such as e-mail which can also be modified. When modifying this and saving changes, an email should arrive to the new one to verify it.
The password can also be changed by filling in the password and new password fields and clicking on the Save changes button.
