The Analytics integration API guide is written for developers who are interested in integrating Fabric8-Analytics stack-analyses or component-analyses services within their applications.

The integration guide provides two examples, which describe its usage and describes the other API resources you can call to use Fabric8-Analytics.

Before you start

1. About OpenShift.io analytics platform

OpenShift.io-analytics is an open source analytics platform aimed primarily at assisting developers in getting insights and recommendations on the stacks used for developing applications. This platform can be used to get an overview and recommendations for single application components as well.

1.1. Supported ecosystems

OpenShift.io-analytics stack-analyses currently analyzes application stacks of the following ecosystems:

  1. Maven Spring Boot

  2. Maven Vert.x

  3. Maven WildFly Swarm

Support for more ecosystems will be introduced in the near future.

2. Getting OpenShift.io authentication token

You require an OpenShift.io authentication token to invoke all OpenShift.io-analytics API resources. Note that the authentication should be kept private and secure.

Get the OpenShift.io authentication token as follows:

  1. Log into OpenShift.io.

  2. On your OpenShift.io home page, click your name on the top right corner of the screen to see the drop-down list.

  3. Select Profile from the list to see your profile page.

    Profile menu button
  4. Click Edit Profile to edit your profile.

    Edit profile button
  5. In the edit profile page displayed, copy your Personal Access Token.

    Edit profile
Your personal access token is meant to be private and confidential. Do not share it with others.

You can now use this token in the various API resources mentioned below.

Using analytics APIs

3. API specifications

The following section lists the primary API endpoints you can use to integrate OpenShift.io-analytics within your application.

3.1. POST /stack-analyses

3.1.1. Purpose

Submits an application stack analysis request.

You require an OpenShift.io authentication token to invoke this method.

3.1.2. Resource URL

For information about the resource URL, reach out to us on the OpenShift.io support chat channel at https://chat.openshift.io or email us at openshiftio@redhat.com.

3.1.3. Resource information

Response Format

JSON

Requires Authentication

Yes

3.1.4. Parameters

Name

Required

Description

Example

manifest[]

required

Ecosystem specific Manifest file(s) available in the application. One can provide multiple manifest files to invoke the method.

@pom.xml

filePath[]

required

Corresponding manifest file’s directory information. Care has to be taken to map the manifest filenames and file paths correctly.

/home/JohnDoe

origin

optional

Originator of the request. Can be the name of an application integrating to the endpoint. Maintained for historical reasons.

"my-app"

3.1.5. Example request with cURL

curl -k -H "Authorization: Bearer <openshift.io authentication token>" -F "manifest[]=@./pom.xml" -F "filePath[]=/home/JohnDoe"https://<recommender api url>/api/v1/stack-analyses

3.1.6. Example response:

Success

{
    "id": "add9caf0a1ff47969a8f27a4241a0230",
    "status": "success",
    "submitted_at": "2018-04-10 08:59:24.472832"
}

Failure

401:
{
  "error": "Authentication failed - could not decode JWT token"
}

3.2. GET /stack-analyses/{request ID}

3.2.1. Purpose

Fetches stack analysis response by using the request identifier returned by /stack-analyses POST.

You require an OpenShift.io authentication token to invoke this method.

3.2.2. Resource URL

For information about the resource URL, reach out to us on the OpenShift.io support chat channel at https://chat.openshift.io or email us at openshiftio@redhat.com.

3.2.3. Resource information

Response Format

JSON

Requires Authentication

Yes

3.2.5. Example request with cURL

curl -k -H "Authorization: Bearer <openshift.io authentication token>" https://<recommender api url>/api/v1/stack-analyses/421249d9e1e5464cbf3e77dde4941463

3.2.6. Example response

Success

{
    "finished_at": "2018-04-10T08:59:25.010455",
    "release": "None:None:None",
    "request_id": "add9caf0a1ff47969a8f27a4241a0230",
    "result": [
        {
            "manifest_file_path": "/some",
            "manifest_name": "pom.xml",
            "recommendation": {
                "alternate": [],
                "companion": [
                    {
                        "code_metrics": {
                            "average_cyclomatic_complexity": -1,
                            "code_lines": -1,
                            "total_files": -1
                        },
                        "confidence_reason": 28.57142857142857,
                        "cooccurrence_count": 4,
                        "cooccurrence_probability": 28.57142857142857,
                        "ecosystem": "maven",
                        "github": {
                            "contributors": -1,
                            "dependent_projects": "0",
                            "dependent_repos": "65",
                            "first_release_date": "N/A",
                            "forks_count": -1,
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "latest_release_duration": "2018-01-15 15:59:36",
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "size": "N/A",
                            "stargazers_count": -1,
                            "total_releases": "37",
                            "used_by": [
                                {
                                    "name": "Craftware/Kornell",
                                    "stars": 12
                                },
                                {
                                    "name": "fabric8-launcher/launcher-backend",
                                    "stars": 4
                                },
                                {
                                    "name": "fabric8io/fabric8-forge",
                                    "stars": 7
                                },
                                {
                                    "name": "kiegroup/guvnor",
                                    "stars": 159
                                },
                                {
                                    "name": "m-reza-rahman/pragmatic-microservices-lab",
                                    "stars": 20
                                },
                                {
                                    "name": "mbiarnes/guvnor",
                                    "stars": 0
                                },
                                {
                                    "name": "redhat-developer-demos/kubernetes-lab",
                                    "stars": 7
                                },
                                {
                                    "name": "redhat-helloworld-msa/hola",
                                    "stars": 7
                                },
                                {
                                    "name": "wildfly-swarm/tutorial",
                                    "stars": 14
                                },
                                {
                                    "name": "wildfly-swarm/wildfly-swarm",
                                    "stars": 203
                                }
                            ],
                            "watchers": -1
                        },
                        "latest_version": "2018.3.1",
                        "licenses": [
                            "AL2"
                        ],
                        "name": "org.wildfly.swarm:jaxrs-cdi",
                        "osio_user_count": 0,
                        "reason": "Package org.wildfly.swarm:jaxrs-cdi appears in 4 different stacksalong with the provided input stack. Do you want to consider adding this Package?",
                        "security": [],
                        "topic_list": [
                            "http",
                            "service",
                            "rest"
                        ],
                        "version": "2018.3.1"
                    },
                    {
                        "code_metrics": {
                            "average_cyclomatic_complexity": -1,
                            "code_lines": -1,
                            "total_files": -1
                        },
                        "confidence_reason": 50,
                        "cooccurrence_count": 7,
                        "cooccurrence_probability": 50,
                        "ecosystem": "maven",
                        "github": {
                            "contributors": -1,
                            "dependent_projects": "0",
                            "dependent_repos": "138",
                            "first_release_date": "N/A",
                            "forks_count": -1,
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "latest_release_duration": "2017-11-06 19:17:18",
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "size": "N/A",
                            "stargazers_count": -1,
                            "total_releases": "33",
                            "used_by": [
                                {
                                    "name": "ALRubinger/hc-swarm-alr-oso",
                                    "stars": 0
                                },
                                {
                                    "name": "bfh-study/sanctions-list-backend",
                                    "stars": 1
                                },
                                {
                                    "name": "fabric8-launcher/launcher-backend",
                                    "stars": 3
                                },
                                {
                                    "name": "gastaldi/hc",
                                    "stars": 0
                                },
                                {
                                    "name": "jclingan/swarm-crud-jc",
                                    "stars": 0
                                },
                                {
                                    "name": "mbiarnes/guvnor",
                                    "stars": 0
                                },
                                {
                                    "name": "redhat-helloworld-msa/hola",
                                    "stars": 7
                                },
                                {
                                    "name": "weweave/tubewarder",
                                    "stars": 10
                                },
                                {
                                    "name": "wildfly-extras/wildfly-microprofile-config",
                                    "stars": 3
                                },
                                {
                                    "name": "wildfly-swarm/wildfly-swarm",
                                    "stars": 196
                                }
                            ],
                            "watchers": -1
                        },
                        "latest_version": "2018.3.2",
                        "licenses": [
                            "AL2"
                        ],
                        "name": "org.wildfly.swarm:cdi",
                        "osio_user_count": 0,
                        "reason": "Package org.wildfly.swarm:cdi appears in 7 different stacksalong with the provided input stack. Do you want to consider adding this Package?",
                        "security": [],
                        "topic_list": [
                            "integration"
                        ],
                        "version": "2018.3.2"
                    }
                ],
                "input_stack_topics": {
                    "org.wildfly.swarm:jaxrs": [
                        "webservice",
                        "rest"
                    ],
                    "org.wildfly.swarm:monitor": [
                        "monitor"
                    ]
                },
                "manifest_file_path": "/some",
                "missing_packages_pgm": [],
                "usage_outliers": []
            },
            "user_stack_info": {
                "analyzed_dependencies": [
                    {
                        "code_metrics": {
                            "average_cyclomatic_complexity": -1,
                            "code_lines": -1,
                            "total_files": -1
                        },
                        "ecosystem": "maven",
                        "github": {
                            "contributors": -1,
                            "dependent_projects": "0",
                            "dependent_repos": "39",
                            "first_release_date": "Apr 16, 2010",
                            "forks_count": -1,
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "latest_release_duration": "2017-09-05 19:59:04",
                            "open_issues_count": -1,
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "size": "N/A",
                            "stargazers_count": -1,
                            "total_releases": "33",
                            "used_by": [
                                {
                                    "name": "ALRubinger/hc-swarm-alr-oso",
                                    "stars": 0
                                },
                                {
                                    "name": "davsclaus/minishift-hello",
                                    "stars": 3
                                },
                                {
                                    "name": "eclipse/microprofile-health",
                                    "stars": 8
                                },
                                {
                                    "name": "gastaldi/hc",
                                    "stars": 0
                                },
                                {
                                    "name": "inoxx03/wf-swarm-hc-nexus",
                                    "stars": 0
                                },
                                {
                                    "name": "inoxx03/wfs-hc",
                                    "stars": 0
                                },
                                {
                                    "name": "inoxx03/wfs-health-check-live",
                                    "stars": 0
                                },
                                {
                                    "name": "nickschuetz/nickswarm",
                                    "stars": 0
                                },
                                {
                                    "name": "wildfly-swarm-openshiftio-boosters/wfswarm-health-check-redhat",
                                    "stars": 0
                                },
                                {
                                    "name": "wildfly-swarm/wildfly-swarm",
                                    "stars": 201
                                }
                            ]
                        },
                        "latest_version": "2017.10.0",
                        "license_analysis": {
                            "_message": "Representative license found",
                            "_representative_licenses": "apache 2.0",
                            "conflict_licenses": [],
                            "outlier_licenses": [],
                            "status": "Successful",
                            "synonyms": {
                                "AL2": "apache 2.0"
                            },
                            "unknown_licenses": []
                        },
                        "licenses": [
                            "AL2"
                        ],
                        "name": "org.wildfly.swarm:monitor",
                        "osio_user_count": 0,
                        "security": [],
                        "topic_list": [
                            "monitor"
                        ],
                        "version": "2017.10.0"
                    },
                    {
                        "code_metrics": {
                            "average_cyclomatic_complexity": -1,
                            "code_lines": -1,
                            "total_files": -1
                        },
                        "ecosystem": "maven",
                        "github": {
                            "contributors": -1,
                            "dependent_projects": "0",
                            "dependent_repos": "227",
                            "first_release_date": "Apr 16, 2010",
                            "forks_count": -1,
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "latest_release_duration": "2018-02-08 16:22:40",
                            "open_issues_count": -1,
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "size": "N/A",
                            "stargazers_count": -1,
                            "total_releases": "47",
                            "used_by": [
                                {
                                    "name": "ALRubinger/hc-swarm-alr-oso",
                                    "stars": 0
                                },
                                {
                                    "name": "arun-gupta/docker-javaee",
                                    "stars": 6
                                },
                                {
                                    "name": "bfh-study/sanctions-list-backend",
                                    "stars": 1
                                },
                                {
                                    "name": "eclipse/microprofile-health",
                                    "stars": 8
                                },
                                {
                                    "name": "mbiarnes/guvnor",
                                    "stars": 0
                                },
                                {
                                    "name": "weweave/tubewarder",
                                    "stars": 10
                                },
                                {
                                    "name": "wildfly-extras/wildfly-microprofile-config",
                                    "stars": 3
                                },
                                {
                                    "name": "wildfly-swarm-archive/wildfly-swarm-drools",
                                    "stars": 1
                                },
                                {
                                    "name": "wildfly-swarm-openshiftio-boosters/wfswarm-health-check-redhat",
                                    "stars": 0
                                },
                                {
                                    "name": "wildfly-swarm/wildfly-swarm",
                                    "stars": 203
                                }
                            ]
                        },
                        "latest_version": "2018.2.0",
                        "license_analysis": {
                            "_message": "Representative license found",
                            "_representative_licenses": "apache 2.0",
                            "conflict_licenses": [],
                            "outlier_licenses": [],
                            "status": "Successful",
                            "synonyms": {
                                "AL2": "apache 2.0"
                            },
                            "unknown_licenses": []
                        },
                        "licenses": [
                            "AL2"
                        ],
                        "name": "org.wildfly.swarm:jaxrs",
                        "osio_user_count": 0,
                        "security": [],
                        "topic_list": [
                            "webservice",
                            "rest"
                        ],
                        "version": "2017.10.0"
                    }
                ],
                "analyzed_dependencies_count": 2,
                "dependencies": [
                    {
                        "package": "org.wildfly.swarm:monitor",
                        "version": "2017.10.0"
                    },
                    {
                        "package": "org.wildfly.swarm:jaxrs",
                        "version": "2017.10.0"
                    }
                ],
                "distinct_licenses": [
                    "AL2"
                ],
                "ecosystem": "maven",
                "license_analysis": {
                    "conflict_packages": [],
                    "current_stack_license": {},
                    "f8a_stack_licenses": [
                        "apache 2.0"
                    ],
                    "outlier_packages": [],
                    "status": "Successful",
                    "unknown_licenses": {
                        "component_conflict": [],
                        "really_unknown": []
                    }
                },
                "recommendation_ready": true,
                "stack_license_conflict": false,
                "total_licenses": 1,
                "unknown_dependencies": [],
                "unknown_dependencies_count": 0
            }
        }
    ],
    "started_at": "2018-04-10T08:59:24.939611",
    "version": "v1"
}

In-Progress

200:
{
    "error": "Analysis for request ID 'add9caf0a1ff47969a8f27a4241a0230' is in progress"
}

Failure

401:
{
  "error": "Authentication failed - could not decode JWT token"
}

3.3. GET /component-analyses/{ecosystem}/{component name}/{component version}

3.3.1. Purpose

Fetches various data points for a selected component.

You require an OpenShift.io authentication token to invoke this method.

3.3.2. Resource URL

For information about the resource URL, reach out to us on the OpenShift.io support chat channel at https://chat.openshift.io or email us at openshiftio@redhat.com.

3.3.3. Resource information

Response Format

JSON

Requires Authentication

Yes

3.3.5. Example request with cURL

curl -k -H "Authorization: Bearer <openshift.io authentication token>" https://<recommender api url>/api/v1/component-analyses/maven/io.vertx:vertx-core/3.4.1

3.3.6. Example response

Success

{
    "result": {
        "data": [
            {
                "package": {
                    "ecosystem": [
                        "maven"
                    ],
                    "gh_contributors_count": [
                        30
                    ],
                    "gh_forks": [
                        1314
                    ],
                    "gh_issues_last_month_closed": [
                        -1
                    ],
                    "gh_issues_last_month_opened": [
                        -1
                    ],
                    "gh_issues_last_year_closed": [
                        -1
                    ],
                    "gh_issues_last_year_opened": [
                        -1
                    ],
                    "gh_open_issues_count": [
                        156
                    ],
                    "gh_prs_last_month_closed": [
                        -1
                    ],
                    "gh_prs_last_month_opened": [
                        -1
                    ],
                    "gh_prs_last_year_closed": [
                        -1
                    ],
                    "gh_prs_last_year_opened": [
                        -1
                    ],
                    "gh_stargazers": [
                        7381
                    ],
                    "gh_subscribers_count": [
                        591
                    ],
                    "last_updated": [
                        1520569765.48
                    ],
                    "last_updated_sentiment_score": [
                        "2017-10-09"
                    ],
                    "latest_version": [
                        "-1"
                    ],
                    "libio_dependents_projects": [
                        "144"
                    ],
                    "libio_dependents_repos": [
                        "3454"
                    ],
                    "libio_latest_release": [
                        1502117662
                    ],
                    "libio_latest_version": [
                        "3.5.0.Beta1"
                    ],
                    "libio_total_releases": [
                        "48"
                    ],
                    "libio_usedby": [
                        "TechEmpower/FrameworkBenchmarks:2976",
                        "apiman/apiman:366",
                        "boonproject/boon:474",
                        "hawkular/hawkular-apm:132",
                        "isaiah/jubilee:342",
                        "jbosstm/narayana:77",
                        "jhalterman/failsafe:1981",
                        "vert-x3/vertx-stack:78",
                        "wildfly-swarm/wildfly-swarm:204",
                        "wisdom-framework/wisdom:72"
                    ],
                    "name": [
                        "io.vertx:vertx-core"
                    ],
                    "package_dependents_count": [
                        -1
                    ],
                    "package_relative_used": [
                        "not used"
                    ],
                    "sentiment_magnitude": [
                        "0"
                    ],
                    "sentiment_score": [
                        "0"
                    ],
                    "tokens": [
                        "core",
                        "io",
                        "vertx"
                    ],
                    "vertex_label": [
                        "Package"
                    ]
                },
                "version": {
                    "cm_avg_cyclomatic_complexity": [
                        1.34
                    ],
                    "cm_loc": [
                        80586
                    ],
                    "cm_num_files": [
                        441
                    ],
                    "declared_licenses": [
                        "Eclipse Public License - v 1.0",
                        "The Apache Software License, Version 2.0"
                    ],
                    "dependents_count": [
                        11
                    ],
                    "description": [
                        "Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/"
                    ],
                    "last_updated": [
                        1517474419.35
                    ],
                    "licenses": [
                        "Apache 2.0",
                        "EPL 1.0",
                        "MIT License"
                    ],
                    "osio_usage_count": [
                        11
                    ],
                    "pecosystem": [
                        "maven"
                    ],
                    "pname": [
                        "io.vertx:vertx-core"
                    ],
                    "relative_used": [
                        ""
                    ],
                    "shipped_as_downstream": [
                        false
                    ],
                    "version": [
                        "3.4.1"
                    ],
                    "vertex_label": [
                        "Version"
                    ]
                }
            }
        ],
        "recommendation": {}
    },
    "schema": {
        "name": "analyses_graphdb",
        "url": "http://<recommender api url>/api/v1/schemas/api/analyses_graphdb/1-2-0/",
        "version": "1-2-0"
    }
}

Failure

401:
{
  "error": "Authentication failed - could not decode JWT token"
}
404:
{
  "error": "No data found for maven Package io.vertx:vertx-core/3.4.1"
}