AppInspect API endpoint reference

This topic gives summary and detailed endpoint descriptions for REST resources within the Splunk AppInspect API. It contains the following sections:

Authentication

To obtain an authentication token, send a GET request to the /2.0/rest/login/splunk endpoint on api.splunk.com. The JSON response contains the token assigned to the "token" key.

GET /2.0/rest/login/splunk

https://api.splunk.com/2.0/rest/login/splunk

Description

Provides access to api.splunk.com to obtain a JSON Web token (JWT) using basic authentication.
HTTP Method: GET
Authentication: Basic Authentication
Response Codes: 200, 401

GET /2.0/rest/login/splunk method detail

Response keys
Key Description
status_code An HTTP response code. The returned code will be either 200 (OK) or 401 (Bad Request).
status The status of the request.
msg A detailed description of the request status.
data A JSON object containing both the token and user information.

Examples

Basic Auth Request
import requests
from requests.auth import HTTPBasicAuth
uri = "https://api.splunk.com/2.0/rest/login/splunk"
response = requests.get(uri, auth=HTTPBasicAuth("myuser", "mypassword"))
user_token = response.json().get("data").get("token")
print(user_token)
JSON Response
{
    "status_code": 200,
    "status": "success",
    "msg": "Successfully authenticated user and assigned a token",
    "data": {
        "token": "<auth_token>",
        "user": {
            "name": "SPLUNK USER",
            "email": "splunker@example.com",
            "username": "mrsplunker",
            "groups": [
                "Decrypt JWT Token"
            ]
        }
    }
}

AppInspect API

To use the AppInspect API, you send the Splunk app package in a POST request to the /v1/app/validate endpoint on appinspect.splunk.com. The JSON response contains the request ID. Then you send the request ID in a GET request to the /v1/app/validate/status/{request_id} endpoint on appinspect.splunk.com. The JSON response contains a detailed report of the checks run and their results.

Note: Within this section's examples, <auth_token> is a placeholder for an authorization token, and <app_package> is a placeholder for a Splunk app's package file (a .tgz file).

POST /v1/app/validate

https://appinspect.splunk.com/v1/app/validate

Description

Submits a Splunk app to be validated against standard certification criteria.
HTTP Method: POST
Authentication: Bearer token (JWT) obtained from splunk.com.
Response Codes: 200, 422, 401

Examples

Basic request

cURL:

curl https://appinspect.splunk.com/v1/app/validate 
   -H "Authorization: Bearer <auth_token>" \
   -F app_package=<app_package>

Python:

import os
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

url = "https://appinspect.splunk.com/v1/app/validate"
file_path = "<full_path_to_file>"
user_token="<auth_token>"
app_name = os.path.basename(file_path)

fields = (
{{ ('app_package', (app_name, open(file_path, "rb"))),}}
{{ ('included_tags', 'cloud'),}}
{{ ('included_tags', 'self-service'),}}
)
payload = MultipartEncoder(fields=fields)
headers = {"Authorization": "bearer {}".format(
{{ user_token), "Content-Type": payload.content_type, "max-messages": "all"}}}
response = requests.request("POST", url, data=payload, headers=headers)

print(response.status_code)
print(response.json())
Including and excluding tags and header values

You can explicitly include and exclude tags from a validation by including additional options in your request. Specifically, including the included_tags and excluded_tags options will include and exclude, respectively, the tags you specify from a validation.

Use the max-messages header value to specify the number of results AppInspect returns. By default, AppInspect returns 25 results. You can set the value to any positive, non-zero integer or all to return all results.

See the following examples to learn how to use tags and header values:

cURL:

# For tag inclusion/exclusion
curl https://appinspect.splunk.com/v1/app/validate 
   -H "Authorization: Bearer <auth_token>" \
   -H "max-messages: all" \
   -H "Content-Type: multipart/form-data" \
   -F app_package=<app_package> \
   -F "included_tags=<tag_to_include>" \
   -F "excluded_tags=<tag_to_exclude>"

Python:

import os
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

url = "https://appinspect.splunk.com/v1/app/validate"
file_path = "<full_path_to_file>"
user_token="<auth_token>"
app_name = os.path.basename(file_path)

fields = {}
fields.update({"app_package": (app_name, open(file_path, "rb"))})
fields.update({"included_tags": "manual"}) #optional
fields.update({"excluded_tags": "cloud"}) #optional
payload = MultipartEncoder(fields=fields)
headers = { "Authorization": "bearer {}".format(user_token), "Content-Type": payload.content_type, "max-messages":"all"}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.status_code)
print(response.json())

GET /v1/app/validate/status/{request_id}

https://appinspect.splunk.com/v1/app/validate/status/{request_id}

Description

Returns the status of an in-process request using the request_id returned from an initial validation request (/v1/app/validate).Once the request is complete, this endpoint will return information for a limited time.  Note that the app information in 'info' may change if multiple apps are submitted at once. For the full report use the /report/{request_id} endpoint.
HTTP Method: GET
Authentication: Bearer token (JWT) obtained from splunk.com.
Response Codes: 200, 401

GET /v1/app/validate/status/{request_id} method detail

Response keys
Key Description
request_id An alphanumeric string that uniquely identifies this request.
app_name The name of the app as set in app.conf for the app currently being checked.
app_version The version of the app as set in app.conf.
status One of PENDING, PREPARING, PROCESSING, SUCCESS, or ERROR.
checks False metadata about checks that have been run or are running in this current check. Pending checks are not listed.

Examples

JSON Response
{
 "info": {
    "app_name": "An Example Splunk App",
    "app_version": "0.1",
    "checks":
        inprogress: 10
        completed: [
            {
            error: 6,
            failure: 2,
            manual_check: 20,
            not_applicable: 30,
            skipped: 1,
            success: 74
            }
        ]
 },
 "request_id": "93cad1ef-925f-45cd-b385-1083285c3109",
 "status": "PROCESSING"
}

GET /v1/app/report/{request_id}

https://appinspect.splunk.com/v1/app/report/{request_id}

Description

Returns the report data for a given request. The report endpoint will return a HTTP Status code 404 (Not Found) until validation of the app is complete.
HTTP Method: GET
Authentication: Bearer token (JWT) obtained from splunk.com.
Response Codes: 200, 404, 401

Example

JSON Response
{
  "cloc": "      10 text files.",
  "links": [
    {
      "href": "/v1/app/report/7779ce08-1adf-489f-870a-6c1ea6a47948",
      "rel": "self"
    }
  ],
  "reports": [
    {
      "app_author": "The App Author in app.conf",
      "app_description": "The App Description in app.conf.",
      "app_hash": "bb4230ee815dd62b02e0b66780809823",
      "app_name": "The App Name in app.conf",
      "app_version": "The App Version",
      "groups": [
        {
          "checks": [
            {
              "description": "Check that changes made to default/limits.conf are documented.",
              "messages": [
                {
                  "code": "reporter.not_applicable(\"No limits.conf found.\")",
                  "filename": "check_limits_configuration_file.py",
                  "line": 23,
                  "message": "No limits.conf found.",
                  "result": "not_applicable"
                }
              ],
              "name": "check_limits_conf",
              "result": "not_applicable"
            }
          ],
          "description": "Limits.conf file standards",
          "name": "check_limits_configuration_file"
        }
      ],
      "metrics": {
        "end_time": "2016-09-09T04:50:40.723074",
        "execution": 20.650866,
        "start_time": "2016-09-09T04:50:20.072208"
      },
      "run_parameters": {
        "api_request_id": "e815de54-7648-11e6-93d8-0242ac120007",
        "excluded_tag": null,
        "identity": "my_id",
        "package_location": "/opt/packages/e815de54-7648-11e6-93d8-0242ac120007-app.tgz",
        "splunk_version": null,
        "splunkbase_id": "unknown",
        "tag": null,
        "version": null
      },
      "summary": {
        "error": 0,
        "failure": 3,
        "manual_check": 28,
        "not_applicable": 52,
        "skipped": 0,
        "success": 83,
        "warning": 0
      }
    }
  ],
  "request_id": "7779ce08-1adf-489f-870a-6c1ea6a47948",
  "summary": {
    "error": 0,
    "failure": 3,
    "manual_check": 28,
    "not_applicable": 52,
    "skipped": 0,
    "success": 83,
    "warning": 0
  }
}

GET /v1/app/report

https://appinspect.splunk.com/v1/app/report

Description

Returns a list of reports accessible for the current identity.
HTTP Method: GET
Authentication: Bearer token (JWT) obtained from splunk.com.
Response Codes: 200, 401

Example

JSON Response
{
    "reports": [
        {
            "app_hash": "d91f76d00996c3509ee9a652d99376b9",
            "app_name": "Splunk App for Stream",
            "app_version": "6.4.2",
            "links": [
                {
                    "href": "/v1/report/a9e930a1-3989-422b-8062-baa8a3ca58e2",
                    "rel": "self"
                }
            ],
            "request_id": "a9e930a1-3989-422b-8062-baa8a3ca58e2"
        },
        {
            "app_hash": "d91f76d00996c3509ee9a652d99376b9",
            "app_name": "An test app",
            "app_version": "1.2.3",
            "links": [
                {
                    "href": "/v1/report/c5ec4422-2c9f-4077-8936-8854cf1f61bf",
                    "rel": "self"
                }
            ],
            "request_id": "c5ec4422-2c9f-4077-8936-8854cf1f61bf"
        }
    ]
}

GET /v1/group

https://appinspect.splunk.com/v1/group

Description

The group endpoint returns a list of certification groups with hypermedia links.
HTTP Method: GET
Authentication: Bearer token (JWT) obtained from splunk.com.
Response Codes: 200, 401

Example

JSON Response
 {
    "groups": [
        {
            "description": "Directory Structure Standards",
            "links": [
                {
                    "href": "/v1/group/check_application_structure",
                    "rel": "self"
                }
            ],
            "name": "check_application_structure"
        },
        {
            "description": "Props Configuration file standards",
            "links": [
                {
                    "href": "/v1/group/check_props_configuration_file",
                    "rel": "self"
                }
            ],
            "name": "check_props_configuration_file"
        },
...
}

GET /v1/check

https://appinspect.splunk.com/v1/check

Description

The check endpoint returns a list of checks with hypermedia links.
HTTP Method: GET
Authentication: Bearer token (JWT) obtained from splunk.com.
Response Codes: 200, 401

Example

JSON Response
 {
    "checks": [
        {
            "description": "Check there is no 'local' directory.",
            "html": "

Check there is no 'local' directory.

", "links": [ { "href": "/v1/check/check_that_local_does_not_exist", "rel": "self" }, { "href": "/v1/group/check_application_structure", "rel": "group" } ], "name": "check_that_local_does_not_exist", "tags": [ "splunk_appinspect", "appapproval", "cloud" ] }, { "description": "Ensure that all metadata is supplied in default.meta, not local.meta.", "html": "

Ensure that all metadata is supplied in default.meta, not local.meta.

", "links": [ { "href": "/v1/check/check_for_local_meta", "rel": "self" }, { "href": "/v1/group/check_application_structure", "rel": "group" } ], "name": "check_for_local_meta", "tags": [ "splunk_appinspect" ] }, ... }

Errors

All endpoints are secured via AppInspect PingFed Integration. Endpoints will return 401 in the event of a failed authorization.

No Header

{
"code": "authorization_header_missing",
"description": "Authorization header is expected"
}

Invalid Token

{
"code": "Unauthorized",
"description": "Failed to authenticate"
}

Examples

Get an auth token

cURL

curl 
   -X GET \
   -H "Authorization: Basic <auth_token>" \
   -H "Cache-Control: no-cache" "https://api.splunk.com/2.0/rest/login/splunk"

Python

import requests
url = "https://api.splunk.com/2.0/rest/login/splunk"
headers = {
    'authorization': "Basic <auth_token>",
    'cache-control': "no-cache"
    }
response = requests.request("GET", url, headers=headers)
print(response.text)

Validate a package

cURL

curl 
   -X POST \
   -H "Authorization: bearer <auth_token>" \
   -H "Cache-Control: no-cache" \
   -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \
   -F "app_package=@testapp.tar.gz" "https://appinspect.splunk.com/v1/app/validate"