Analytics Library REST API

  • reference
    +

    Overview

    The Analytics Library REST API is provided by the Analytics service. This API enables you to manage the libraries that are used to create SQL++ for Analytics user-defined functions.

    Version information

    Version : 0.1

    Host information

    {scheme}://{host}:{port}

    The URL scheme, host, and port are as follows.

    Component Description

    scheme

    The URL scheme. Use https for secure access.

    Values: http, https
    Example: http

    host

    The host name or IP address of a node running the Analytics service.

    Example: localhost

    port

    The Analytics service REST port. Use 18095 for secure access.

    Values: 8095, 18095
    Example: 8095

    Resources

    This section describes the operations available with this REST API.

    Delete a Library

    DELETE /analytics/library/{scope}/{library}

    Description

    Deletes the specified library entirely.

    Produces
    • application/json

    Parameters

    Path Parameters

    Name Description Schema

    library
    required

    The name of a library.

    String

    scope
    required

    The name of the Analytics scope containing the library.

    The scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

    String

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    Object

    404

    Not found. The library name in the path may be incorrect.

    500

    Internal server error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Security

    Type Name

    http (basic)

    Full Admin

    Example HTTP Request

    The example below deletes the mylib library from the travel-sample.inventory scope.

    Curl request
    curl -X DELETE \
    http://localhost:8095/analytics/library/travel-sample%2Finventory/mylib \
    -u Administrator:password
    The dot separator within the scope name is converted to a slash (/), which is then URL-encoded as %2F.

    Read All Libraries

    GET /analytics/library

    Description

    Returns all libraries and functions.

    Produces
    • application/json

    Responses

    HTTP Code Description Schema

    200

    Success. Returns an array of objects, each of which contains information about a single library.

    Libraries array

    404

    Not found. The path may be missing its trailing slash.

    500

    Internal server error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Security

    Type Name

    http (basic)

    Analytics Admin

    Example HTTP Request

    The example below fetches all defined libraries.

    Curl request
    curl -X GET \
    http://localhost:8095/analytics/library/ \
    -u Administrator:password

    Example HTTP Response

    Response 200
    [ {
      "scope" : "travel-sample/inventory",
      "hash_md5" : "b0e764a12aa922de80b14bab9a7d2fb3",
      "name" : "mylib"
    } ]

    Create or Update a Library

    POST /analytics/library/{scope}/{library}

    Description

    Creates the specified library and its associated functions. If the specified library exists, the existing library is overwritten.

    • To add a function to a library, update the library with all existing functions, plus the new function.

    • To update a function, update the library with all existing functions, including the updated function definition.

    • To delete a function from a library, update the library with all existing functions, without the deleted function.

    Consumes
    • multipart/form-data

    Produces
    • application/json

    Parameters

    Path Parameters

    Name Description Schema

    library
    required

    The name of a library.

    String

    scope
    required

    The name of the Analytics scope containing the library.

    The scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

    String

    Form Parameters

    Name Description Schema

    data
    required

    The library and all its dependencies, packaged by shiv.

    File (binary)

    type
    required

    The language of the library.

    Values: "python"

    String

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    Object

    400

    Bad request. A parameter has an incorrect value.

    500

    Internal server error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Security

    Type Name

    http (basic)

    Full Admin

    Example HTTP Request

    The example below creates or updates a library called mylib in the travel-sample.inventory scope. The Python code is stored in a file called lib.pyz.

    Curl request
    curl -X POST \
    http://localhost:8095/analytics/library/travel-sample%2Finventory/mylib \
    -u Administrator:password \
    -d type=python
    -d data=lib.pyz
    The dot separator within the scope name is converted to a slash (/), which is then URL-encoded as %2F.

    Definitions

    This section describes the properties consumed and returned by this REST API.

    Errors

    Object

    Property Schema

    error
    required

    An error message.

    String

    Libraries

    Object

    Property Schema

    scope
    optional

    The name of the Analytics scope containing the library.

    The scope name may contain one or two identifiers, separated by a slash (/).

    Example: "travel-sample/inventory"

    String

    hash_md5
    optional

    A MD5 hash of the library residing on the server.

    String

    name
    optional

    The name of the library.

    Example: "mylib"

    String

    Security

    The Analytics Library REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.

    Full Admin

    To Create or Update a Library or Delete a Library, users must have the Full Admin RBAC role.

    Type : http

    Analytics Admin

    To Read All Libraries, users must have one of the following RBAC roles:

    • Full Admin
    • Cluster Admin
    • Analytics Admin

    Type : http

    Refer to Roles for more details.