# Management Console GraphQL API ## Table of Contents * [Getting Started](#Getting-Started) * [Overview](#Overview) * [About GraphQL](#About-Graphql) * [The GraphQL API Endpoint](#The-GraphQL-API-Endpoint) * [Calling the GraphQL API](#Calling-the-GraphQL-API) * [Authentication](#Authentication) * [Request Body](#Request-Body) * [Example API Call](#Example-API-Call) * [Supported Queries and Mutations](#Supported-Queries-and-Mutations) * [Queries](#Queries) * [Mutations](#Mutations) * [Error Handling](#Error-Handling) * [GraphQL Client Libraries](#GraphQL-Client-Libraries) ## Getting Started This section goes over several hands-on tutorials that can be followed for getting up and running quickly with working examples with the Management Console Public APIs. * [Postman Tutorial](./appendix/postman/tutorial.md) * [NodeJS Tutorial](./appendix/nodejs/tutorial.md) * [Python Tutorial](./appendix/python/tutorial.md) ## Overview The Management Console API for Teradata Vantage delivered as-a-service provides programatic access to common database elasticity operations. With the availability of the new API, authorized users of Vantage delivered as-a-service can now create custom scripts/apps (clients) to directly manage their Teradata systems. For example, an administrator can use the MC Public API to manage costs by starting/stopping a Site's SQL Engine based on usage requirements. The MC Public APIs currently include the following functionality: * Get API version details * user * List your User's Roles * Assume a Role * Site * List all Sites * Get Site details * Site SQL Engine * Get Site SQL Engine * Start Site SQL Engine * Stop Site SQL Engine * Scale Out/Scale In SQL Engine (node count) * Scale Up/Scale Down SQL Engine (node instance type) * Storage Resize SQL Engine * Get SQL Engine Operation * Site ML Engine * Get Site ML Engine * Start Site ML Engine * Stop Site ML Engine * Get ML Engine Operation ## About GraphQL GraphQL is a query language for APIs that: * Describes API capabilities through a strongly [Typed Schema](https://graphql.org/learn/schema/) * Learn the supported capabilities of the API through a type schema that describes all entry points (Queries/Mutations) and the schema of the returned data * The GraphQL schema is defined through GraphQL's Schema Definition Language (SDL) * Allows clients to Request what is needed through [Queries and Mutations](https://graphql.org/learn/queries/) * GraphQL API calls return exactly what was requested (not more or less) * Clients control the data they require * Allows clients to discover the API schema through [Introspection](https://graphql.org/learn/introspection/) * Discover API documentation through introspection (e.g. GraphQL Playground and Voyager tools) The Official GraphQL specification can be found [here](https://graphql.github.io/graphql-spec/June2018/). ## The GraphQL API Endpoint * Authentiction with Teradata Vantage user credentials. * The GraphQL MC Public API endpoint is: `https://api.vantage.teradata.com/graphql` * The GraphQL Schema Definition Language (SDL) can be downloaded from: `https://api.vantage.teradata.com/graphql/sdl` * The SDL can be imported in your client to help build custom query/mutations ## Calling the GraphQL API The GraphQL API is an HTTP endpoint, similar to a REST API. The difference is in the content of the request (GraphQL Specification - SDL) vs a REST API's endpoint path, headers, and request body. All calls to the GraphQL endpoint (Queries or Mutations) will use the `POST` HTTP method. ### Authentication The MC GraphQL API is secured with Basic Authentication (see [RFC 7617](https://tools.ietf.org/html/rfc7617)). To make calls to this API (any GraphQL Query or Mutation), will require the following `Authorization` header: ```json { ... "Authorization": "Basic " ... } ``` ### Request Body Request body format ```json { "operationName":"myOperationName", "query":"query myOperationName {...}" } ``` ### Example API Call with cURL Example SQL Engine Stop call (Mutation) with cURL can be seen below. Additional tutorials and examples can be found in the [Getting Started](#Getting-Started) section above. ```bash curl 'https://api.vantage.teradata.com/graphql' -H 'authorization: Basic ' -H 'content-type: application/json' --data-binary '{"operationName":"stopSqlEngine","variables":{},"query":"mutation stopSqlEngine { stopSqlEngine(siteId: \"TDICA01780PRD00\") {id, name, status, startTime, endTime, details }}"}' ``` ## Supported Queries and Mutations ### Queries Query | Inputs | Details --- | --- | --- api | n/a | API Version Details. user | n/a | Get your User's policy roles. sites | n/a | List your Teradata Sites. site | id (Site ID) | Get Details on a specific site. sqlEngine | siteId | Get details on a specific SQL Engine for a given Site ID. getSqlEngineOperation | siteId, operationId | Get details on a specific SQL Engine operation. mlEngine | siteId | Get details on a specific ML Engine for a given Site ID. getMlEngineOperation | siteId, operationId | Get details on a specific ML Engine operation. ### Mutations Mutation | Inputs | Details --- | --- | --- assumeRole | targetRole (ROLE) | Change/Assume role for your user. startSqlEngine | siteId (Site ID for SQL Engine) | Start SQL Engine for given Site ID. stopSqlEngine | siteId (Site ID for SQL Engine) | Stop SQL Engine for given Site ID. scaleOutInSqlEngine | siteId (Site ID for SQL Engine), nodeCount (number of nodes to scale up/down to) | Scale Out or In SQL Engine to provided node count for given Site ID. scaleUpDownSqlEngine | siteId (Site ID for SQL Engine), instanceType (node instance type to change to) | Scale Up or Down SQL Engine to provided instance type for given Site ID. storageResizeSqlEngine | siteId (Site ID for SQL Engine), value (new storage size value), units (storage size units) | Storage Resize for SQL Engine to provided total value in units. startMlEngine | siteId (Site ID for ML Engine) | Start ML Engine for given Site ID. stopMlEngine | siteId (Site ID for ML Engine) | Stop ML Engine for given Site ID. ## Error Handling Similar to REST APIs, calls to GraphQL APIs can also return error responses. Some examples can be unauthorized/forbidden errors, resource not found, operation failed, etc. Error details from a GraphQL API call are contained in the returned response body. Since a GraphQL call can span multiple services, error objects are returned as a list in the `errors` portion of the response body. The structure of an error object is as described below: ```bash "error": { "message": String # message string "extensions": { # additional metadata about the error "code": String # error code, e.g. UNAUTHORIZED, FORBIDDEN, BAD_USER_INPUT, etc. ... # other error related details }, "path": [String] # Query path(s) that resulted in this error "locations": ["line": Int, "column": Int] # Query line(s) and column(s) that resulted in this error } ``` The error code is contained in the `extensions` portion of the error object in a field named `code`. ### Example Unathorized Response The response to an unauthorized API call. ```bash { "errors": [ { "message": "unauthorized", "extensions": { "code": "UNAUTHORIZED" } } ] } ``` ### Example Not Found Request Response Trying to get the details of a Site that does not exist. ```bash { "errors": [ { "message": "Site for the provided ID 'NOT_EXISTENT_SITE_ID' was not found", "locations": [ { "line": 2, "column": 3 } ], "path": [ "stopSqlEngine" ], "extensions": { "id": "NOT_EXISTENT_SITE_ID", "status": "NOT_FOUND", "code": "BAD_USER_INPUT" } } ], "data": { "stopSqlEngine": null } } ``` ### Example Invalid Request Response Calling SQL Engine Start operation on a Site where that operation is currently not available (e.g. SQL Engine is already running). ```bash { "errors": [ { "message": "SQL Engine START Operation Failed", "locations": [ { "line": 2, "column": 3 } ], "path": [ "startSqlEngine" ], "extensions": { "status": "OPERATION_NOT_AVAILABLE", "availableOperations": [ "SCALE_UP_SCALE_DOWN", "SCALE_OUT_SCALE_IN", "STOP", "STORAGE_RESIZE" ], "details": "SQL Engine START Operation is not available at this time.", "code": "BAD_USER_INPUT" } } ], "data": { "startSqlEngine": null } } ``` ## GraphQL Client Libraries The list below contains popular client libraries for calling GraphQL APIs: [GraphQL Clients](https://graphql.org/code/#graphql-clients)