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.

Before you start

1. About analytics platform

Analytics is an open source 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

The analytics stack-analyses endpoint currently analyzes all application stacks in the Java (Maven) and Node (npm) ecosystems.

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

2. Getting 3scale gateway URL and access key

You require the 3scale gateway URL and access key to invoke all of the analytics API resources mentioned below. For information about the gateway URL and the gateway access key, reach out to us on the fabric8-analytics support chat channel.

Your access key is meant to be private and confidential. Do not share it with others.

Using analytics APIs

3. API specifications

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

3.1. POST /stack-analyses

3.1.1. Purpose

Submits an application stack analysis request.

3.1.2. Resource URL and access key

You require the 3scale gateway URL and access key to invoke all of the analytics API resources mentioned below. For information about the gateway URL and the gateway access key, reach out to us on the fabric8-analytics support chat channel..

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 -X POST -F 'manifest[]=@./pom.xml' -F 'filePath[]=/home/John https://<3scale Gateway URL>/api/v1/stack-analyses/?user_key=<user-key>

3.1.6. Example response:

Success

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

Failure

401:
{
  "message": "Authentication failed",
  "some_description": "Authentication failed",
  "status": 401
}

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.

3.2.2. Resource URL and access key

You require the 3scale gateway URL and access key to invoke all of the analytics API resources mentioned below. For information about the gateway URL and the gateway access key, reach out to us on the fabric8-analytics support chat channel.

3.2.3. Resource information

Response Format

JSON

Requires Authentication

Yes

3.2.5. Example request with cURL

curl https://<3scale APICast Gateway URL>/api/v1/stack-analyses/421249d9e1e5464cbf3e77dde4941463?user_key=<user-key>

3.2.6. Example response

Success

{
    "result": [
        {
            "manifest_file_path": "/home/JohnDoe",
            "recommendation": {
                "missing_packages_pgm": [],
                "usage_outliers": [],
                "alternate": [],
                "input_stack_topics": {
                    "io.vertx:vertx-docgen": [
                        "java",
                        "spring",
                        "library"
                    ],
                    "io.vertx:vertx-auth-common": [
                        "java",
                        "authentication",
                        "authorization"
                    ],
                    "io.vertx:vertx-bridge-common": [
                        "bridge",
                        "vertx",
                        "config",
                        "commons"
                    ],
                    "io.vertx:vertx-auth-htdigest": [
                        "authentication",
                        "vertx"
                    ],
                    "io.vertx:vertx-auth-jwt": [
                        "authentication",
                        "jwt",
                        "token",
                        "authorization"
                    ],
                    "io.vertx:vertx-codegen": [
                        "vertx",
                        "io"
                    ],
                    "io.vertx:vertx-auth-oauth2": [
                        "authentication",
                        "oauth",
                        "vertx",
                        "provider"
                    ],
                    "io.vertx:vertx-core": [
                        "http",
                        "socket",
                        "cluster",
                        "reactive"
                    ]
                },
                "manifest_file_path": "/home/JohnDoe",
                "companion": [
                    {
                        "topic_list": [
                            "event-bus",
                            "jwt",
                            "webapp",
                            "routing"
                        ],
                        "security": [],
                        "confidence_reason": 100,
                        "ecosystem": "maven",
                        "osio_user_count": 0,
                        "name": "io.vertx:vertx-web",
                        "github": {
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "forks_count": -1,
                            "stargazers_count": -1,
                            "watchers": -1,
                            "dependent_repos": "5415",
                            "latest_release_duration": "2018-05-28 11:46:58",
                            "dependent_projects": "33",
                            "total_releases": "21",
                            "size": "N/A",
                            "contributors": -1,
                            "used_by": [
                                {
                                    "name": "BraintagsGmbH/NetRelay",
                                    "stars": 5
                                },
                                {
                                    "name": "gi0baro/FrameworkBenchmarks",
                                    "stars": 0
                                },
                                {
                                    "name": "pac4j/vertx-pac4j",
                                    "stars": 74
                                },
                                {
                                    "name": "prometheus/client_java",
                                    "stars": 348
                                },
                                {
                                    "name": "redhat-developer/reactive-microservices-in-java",
                                    "stars": 39
                                },
                                {
                                    "name": "vert-x3/vertx-hazelcast",
                                    "stars": 35
                                },
                                {
                                    "name": "vert-x3/vertx-ignite",
                                    "stars": 19
                                },
                                {
                                    "name": "vert-x3/vertx-service-discovery",
                                    "stars": 53
                                },
                                {
                                    "name": "vert-x3/vertx-zookeeper",
                                    "stars": 45
                                },
                                {
                                    "name": "voyages-sncf-technologies/tock",
                                    "stars": 23
                                }
                            ],
                            "first_release_date": "N/A",
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            }
                        },
                        "cooccurrence_probability": 100,
                        "cooccurrence_count": 2,
                        "code_metrics": {
                            "code_lines": -1,
                            "average_cyclomatic_complexity": -1,
                            "total_files": -1
                        },
                        "licenses": [
                            "Eclipse Public License - v 2.0",
                            "The Apache Software License, Version 2.0"
                        ],
                        "reason": "Package io.vertx:vertx-web appears in 2 different stacks along with the provided input stack. Do you want to consider adding this Package?",
                        "latest_version": "3.6.0.CR1",
                        "version": "3.6.0.CR1"
                    },
                    {
                        "topic_list": [
                            "logging",
                            "dependency-injection",
                            "api"
                        ],
                        "security": [],
                        "confidence_reason": 100,
                        "ecosystem": "maven",
                        "osio_user_count": 0,
                        "name": "org.slf4j:slf4j-api",
                        "github": {
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "forks_count": -1,
                            "stargazers_count": -1,
                            "watchers": -1,
                            "dependent_repos": "111974",
                            "latest_release_duration": "2018-03-21 22:01:42",
                            "dependent_projects": "10432",
                            "total_releases": "66",
                            "size": "N/A",
                            "contributors": -1,
                            "used_by": [
                                {
                                    "name": "apache/spark",
                                    "stars": 15450
                                },
                                {
                                    "name": "dropwizard/dropwizard",
                                    "stars": 6200
                                },
                                {
                                    "name": "dropwizard/metrics",
                                    "stars": 5377
                                },
                                {
                                    "name": "eclipse/jetty.project",
                                    "stars": 1723
                                },
                                {
                                    "name": "hibernate/hibernate-validator",
                                    "stars": 421
                                },
                                {
                                    "name": "netty/netty",
                                    "stars": 12051
                                },
                                {
                                    "name": "qos-ch/slf4j",
                                    "stars": 885
                                },
                                {
                                    "name": "resteasy/Resteasy",
                                    "stars": 660
                                },
                                {
                                    "name": "rzwitserloot/lombok",
                                    "stars": 5395
                                },
                                {
                                    "name": "spring-projects/spring-security",
                                    "stars": 2042
                                }
                            ],
                            "first_release_date": "N/A",
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            }
                        },
                        "cooccurrence_probability": 100,
                        "cooccurrence_count": 2,
                        "code_metrics": {
                            "code_lines": -1,
                            "average_cyclomatic_complexity": -1,
                            "total_files": -1
                        },
                        "licenses": [
                            "MIT License"
                        ],
                        "reason": "Package org.slf4j:slf4j-api appears in 2 different stacks along with the provided input stack. Do you want to consider adding this Package?",
                        "latest_version": "1.8.0-beta2",
                        "version": "1.8.0-beta2"
                    },
                    {
                        "topic_list": [
                            "vertx"
                        ],
                        "security": [],
                        "confidence_reason": 100,
                        "ecosystem": "maven",
                        "osio_user_count": 0,
                        "name": "io.vertx:vertx-codetrans",
                        "github": {
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "forks_count": -1,
                            "stargazers_count": -1,
                            "watchers": -1,
                            "dependent_repos": "140",
                            "latest_release_duration": "2018-05-28 11:43:27",
                            "dependent_projects": "4",
                            "total_releases": "26",
                            "size": "N/A",
                            "contributors": -1,
                            "used_by": [
                                {
                                    "name": "vert-x3/vertx-dropwizard-metrics",
                                    "stars": 18
                                },
                                {
                                    "name": "vert-x3/vertx-hazelcast",
                                    "stars": 35
                                },
                                {
                                    "name": "vert-x3/vertx-ignite",
                                    "stars": 19
                                },
                                {
                                    "name": "vert-x3/vertx-jdbc-client",
                                    "stars": 34
                                },
                                {
                                    "name": "vert-x3/vertx-mysql-postgresql-client",
                                    "stars": 35
                                },
                                {
                                    "name": "vert-x3/vertx-redis-client",
                                    "stars": 38
                                },
                                {
                                    "name": "vert-x3/vertx-service-discovery",
                                    "stars": 53
                                },
                                {
                                    "name": "vert-x3/vertx-service-factory",
                                    "stars": 16
                                },
                                {
                                    "name": "vert-x3/vertx-unit",
                                    "stars": 16
                                },
                                {
                                    "name": "vert-x3/vertx-zookeeper",
                                    "stars": 45
                                }
                            ],
                            "first_release_date": "N/A",
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            }
                        },
                        "cooccurrence_probability": 100,
                        "cooccurrence_count": 2,
                        "code_metrics": {
                            "code_lines": -1,
                            "average_cyclomatic_complexity": -1,
                            "total_files": -1
                        },
                        "licenses": [
                            "Eclipse Public License - v 1.0",
                            "The Apache Software License, Version 2.0"
                        ],
                        "reason": "Package io.vertx:vertx-codetrans appears in 2 different stacks along with the provided input stack. Do you want to consider adding this Package?",
                        "latest_version": "3.6.0.CR1",
                        "version": "3.6.0.CR1"
                    }
                ]
            },
            "user_stack_info": {
                "license_analysis": {
                    "unknown_licenses": {
                        "really_unknown": [],
                        "component_conflict": []
                    },
                    "conflict_packages": [],
                    "status": "Successful",
                    "f8a_stack_licenses": [
                        "epl 1.0"
                    ],
                    "current_stack_license": {},
                    "outlier_packages": []
                },
                "analyzed_dependencies_count": 1,
                "recommendation_ready": true,
                "unknown_dependencies": [
                    {
                        "name": "io.vertx:vertx-auth-oauth2",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "name": "io.vertx:vertx-bridge-common",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "name": "io.vertx:vertx-codegen",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "name": "io.vertx:vertx-auth-common",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "name": "io.vertx:vertx-auth-jwt",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "name": "io.vertx:vertx-core",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "name": "io.vertx:vertx-auth-htdigest",
                        "version": "3.6.0-SNAPSHOT"
                    }
                ],
                "analyzed_dependencies": [
                    {
                        "license_analysis": {
                            "unknown_licenses": [],
                            "outlier_licenses": [],
                            "status": "Successful",
                            "_message": "Representative license found",
                            "synonyms": {
                                "The Apache Software License, Version 2.0": "apache 2.0",
                                "Eclipse Public License - v 1.0": "epl 1.0"
                            },
                            "conflict_licenses": [],
                            "_representative_licenses": "epl 1.0"
                        },
                        "security": [],
                        "github": {
                            "issues": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            },
                            "forks_count": 12,
                            "open_issues_count": 6,
                            "stargazers_count": 16,
                            "dependent_repos": "194",
                            "latest_release_duration": "2017-08-07 14:53:35",
                            "dependent_projects": "7",
                            "total_releases": "21",
                            "size": "N/A",
                            "contributors": 5,
                            "used_by": [
                                {
                                    "name": "eclipse/vert.x",
                                    "stars": 7178
                                },
                                {
                                    "name": "vert-x3/vertx-auth",
                                    "stars": 44
                                },
                                {
                                    "name": "vert-x3/vertx-jdbc-client",
                                    "stars": 34
                                },
                                {
                                    "name": "vert-x3/vertx-redis-client",
                                    "stars": 36
                                },
                                {
                                    "name": "vert-x3/vertx-rx",
                                    "stars": 81
                                },
                                {
                                    "name": "vert-x3/vertx-service-discovery",
                                    "stars": 51
                                },
                                {
                                    "name": "vert-x3/vertx-service-proxy",
                                    "stars": 41
                                },
                                {
                                    "name": "vert-x3/vertx-stack",
                                    "stars": 78
                                },
                                {
                                    "name": "vert-x3/vertx-sync",
                                    "stars": 56
                                },
                                {
                                    "name": "vert-x3/vertx-web",
                                    "stars": 372
                                }
                            ],
                            "first_release_date": "Apr 16, 2010",
                            "pull_requests": {
                                "month": {
                                    "closed": -1,
                                    "opened": -1
                                },
                                "year": {
                                    "closed": -1,
                                    "opened": -1
                                }
                            }
                        },
                        "osio_user_count": 0,
                        "ecosystem": "maven",
                        "code_metrics": {
                            "code_lines": -1,
                            "average_cyclomatic_complexity": -1,
                            "total_files": -1
                        },
                        "name": "io.vertx:vertx-docgen",
                        "topic_list": [
                            "java",
                            "spring",
                            "library"
                        ],
                        "latest_version": "3.5.0.Beta1",
                        "version": "0.9.1",
                        "licenses": [
                            "Eclipse Public License - v 1.0",
                            "The Apache Software License, Version 2.0"
                        ]
                    }
                ],
                "total_licenses": 2,
                "ecosystem": "maven",
                "stack_license_conflict": false,
                "dependencies": [
                    {
                        "package": "io.vertx:vertx-codegen",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-auth-common",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-auth-htdigest",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-auth-jwt",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-core",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-auth-oauth2",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-bridge-common",
                        "version": "3.6.0-SNAPSHOT"
                    },
                    {
                        "package": "io.vertx:vertx-docgen",
                        "version": "0.9.1"
                    }
                ],
                "unknown_dependencies_count": 7,
                "distinct_licenses": [
                    "Eclipse Public License - v 1.0",
                    "The Apache Software License, Version 2.0"
                ]
            },
            "manifest_name": "pom.xml"
        }
    ],
    "release": "None:None:None",
    "request_id": "b5231ac707594a30916e625ead936e30",
    "finished_at": "2018-11-26T13:20:20.884897",
    "version": "v1",
    "started_at": "2018-11-26T13:20:20.737545"
}

In-Progress

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

Failure

401:
{
  "message": "Authentication failed",
  "some_description": "Authentication failed",
  "status": 401

}

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

3.3.1. Purpose

Fetches various data points for a selected component.

3.3.2. Resource URL and access key

You require the 3scale gateway URL and access key to invoke all of the analytics API resources mentioned below. For information about the gateway URL and the gateway access key, reach out to us on the fabric8-analytics support chat channel.

3.3.3. Resource information

Response Format

JSON

Requires Authentication

Yes

3.3.5. Example request with cURL

curl https://<3scale APICast Gateway URL>/api/v1/component-analyses/maven/io.vertx:vertx-core/3.4.1?user_key=<user-key>

3.3.6. Example response

Success

{
    "schema": {
        "url": "http://<recommender api url>/api/v1/schemas/api/analyses_graphdb/1-2-0/",
        "name": "analyses_graphdb",
        "version": "1-2-0"
    },
    "result": {
        "data": [
            {
                "package": {
                    "name": [
                        "io.vertx:vertx-core"
                    ],
                    "last_updated": [
                        1543237499.48
                    ],
                    "gh_contributors_count": [
                        30
                    ],
                    "gh_forks": [
                        1447
                    ],
                    "gh_issues_last_month_opened": [
                        -1
                    ],
                    "gh_stargazers": [
                        8765
                    ],
                    "last_updated_sentiment_score": [
                        "2017-10-09"
                    ],
                    "vertex_label": [
                        "Package"
                    ],
                    "sentiment_score": [
                        "0"
                    ],
                    "latest_version": [
                        "-1"
                    ],
                    "libio_latest_version": [
                        "3.5.3.CR1"
                    ],
                    "gh_issues_last_month_closed": [
                        -1
                    ],
                    "libio_dependents_projects": [
                        "219"
                    ],
                    "gh_prs_last_month_closed": [
                        -1
                    ],
                    "gh_subscribers_count": [
                        619
                    ],
                    "gh_open_issues_count": [
                        175
                    ],
                    "libio_latest_release": [
                        1530599731
                    ],
                    "libio_dependents_repos": [
                        "6978"
                    ],
                    "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"
                    ],
                    "gh_prs_last_month_opened": [
                        -1
                    ],
                    "tokens": [
                        "core",
                        "io",
                        "vertx"
                    ],
                    "gh_issues_last_year_opened": [
                        -1
                    ],
                    "gh_prs_last_year_closed": [
                        -1
                    ],
                    "sentiment_magnitude": [
                        "0"
                    ],
                    "package_relative_used": [
                        "not used"
                    ],
                    "description": [
                        "Vert.x core contains fairly low level functionality including support for HTTP, TCP, file system access, and various other features. You can use this directly in your own applications, and its used by many of the other components of Vert.x"
                    ],
                    "ecosystem": [
                        "maven"
                    ],
                    "gh_issues_last_year_closed": [
                        -1
                    ],
                    "libio_total_releases": [
                        "55"
                    ],
                    "gh_prs_last_year_opened": [
                        -1
                    ],
                    "package_dependents_count": [
                        -1
                    ]
                },
                "version": {
                    "osio_usage_count": [
                        11
                    ],
                    "version": [
                        "3.4.1"
                    ],
                    "cm_num_files": [
                        441
                    ],
                    "licenses": [
                        "Apache 2.0",
                        "EPL 1.0",
                        "MIT License"
                    ],
                    "pecosystem": [
                        "maven"
                    ],
                    "description": [
                        "Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/"
                    ],
                    "vertex_label": [
                        "Version"
                    ],
                    "relative_used": [
                        ""
                    ],
                    "cm_loc": [
                        80586
                    ],
                    "last_updated": [
                        1536234283.01
                    ],
                    "pname": [
                        "io.vertx:vertx-core"
                    ],
                    "declared_licenses": [
                        "Eclipse Public License - v 1.0",
                        "The Apache Software License, Version 2.0"
                    ],
                    "source_repo": [
                        "maven"
                    ],
                    "dependents_count": [
                        11
                    ],
                    "cm_avg_cyclomatic_complexity": [
                        1.34
                    ],
                    "shipped_as_downstream": [
                        false
                    ]
                }
            }
        ],
        "recommendation": {}
    }
}

Failure

401:
{
  "message": "Authentication failed",
  "some_description": "Authentication failed",
  "status": 401

}
404:
{
  "error": "Package maven/io.vertx:vertx-core/3.4.1 is unavailable. The package will be available shortly, please retry after some time."
}