General Management-API Structure

On This Page

The management APIs are RESTful APIs that use a subset of the JSON API specification to represent request and response data.

Request Syntax

The management-API operations are HTTP requests that you send to a dashboard endpoint using an appropriate HTTP method (such as GET or POST). Data parameters (where required) are passed within the request's HTTP body, in JSON format. The requests conform to the following general format:

    <method> /<resource> HTTP/1.1
Host: <management-APIs URL>
Content-Type: application/json
Cookie: session=<cookie>

    {
    "data": {
        "attributes": {
           <attributes>
        },
        "type": "<type>"
    }
}

    import requests

url = "<management-APIs URL>/<resource>"
headers = {
            "Content-Type": "application/json",
            "Cookie": "session=<cookie>"
          }
payload = {
            "data": {
                "attributes": {
                    <attributes>
                },
                "type": "<type>"
                }
          }

response = requests.<method>(url, json=payload, headers=headers)
print(response.text)

    Following is an explanation of the <...> placeholders used in the request syntax:

    <method>
    The HTTP method for the request — for example, GET (HTTP) or get (Python).
    <resource>
    The full path to the operation's target resource. The path begins with the relevant API endpoint — for example, /api/containers for the Containers API — and is optionally followed by a forward slash (/) and URL resource parameters — for example, /1030 to set the container ID for a Delete Container operation.
    <management-APIs URL>

    The URL of the management-APIs service of a platform tenant. Set this URL to the HTTPS URL of the platform dashboard; for example, https://dashboard.default-tenant.app.mycluster.iguazio.com. In bare-metal deployments, you can alternatively set the URL to http://<dashboard IP>:<port> where <dashboard IP> is the IP address or resolvable host domain name of the dashboard and <port> is 8001, which is the host port on which the management-APIs are served; for example, http://192.168.1.100:8001.

    Note
    To run the examples in this reference, you must replace the sample management-APIs URL in the examples with a tenant web-APIs URL for your platform environment.

    A session cookie that was received from a Create Session operation and is used to authenticate the sender of the request, and authorize the sender to perform management operations. For example, j%3A%7B%22sid%22%3A%20%22a9ce242a-670f-47a8-9c8b-c6730f2794dc%22%7D. For more information, see Create Session.

    <attributes>
    Data attributes that serve as request parameters, where relevant.

    Response Syntax

    A response to a management API request includes an HTTP status code and a related reason phrase (see RFC 7231 6. Response Status Codes). Some successful operations also return, within the data object of the response HTTP body, additional information relating to the operation that was performed, in JSON format. The data structure is operation-specific.

    Success Status Codes

    The following HTTP status codes are returned for successful operations:

    HTTP Method Operation Types Success Status Code
    POST Create 200
    GET List; Get 201
    DELETE Delete 204

    Error Information

    In the event of an error, in addition to the HTTP status code returned in the response, the operation returns, within the response HTTP body, an errors array of error-information JSON objects. Each error-information object has a status element that contains the operation's HTTP status code (for example, 400), and a detail string element that contains a textual description of the error:

    {
    "errors": [
        {
            "status": <HTTP status code>,
            "detail": "<error description>"
        }
    ]
}