API Resources

Requirements

Description

This API allows users to upload the details of an API Resource that are then displayed in Alation Catalog. An API
Resource consists of a url, an HTTP method, a response type, a JSON Schema describing the input(s) to the API Resource, and a JSON Schema describing the output.

Using this API, you can:

  • Create new API Resource Catalog Pages, and place them under folders
  • Retrieve an existing Resource
  • Update the details of an existing API Resource, or relocate it
  • Delete an API Resource. The given Resource will be marked deleted, but can be restored

To upload logical metadata (descriptions, stewards, and custom fields), see Upload Logical Metadata.

Use of JSON Schema

JSON Schema is a web standard used to specify the format of a piece of JSON. This API uses JSON Schema Draft 7 to specify the inputs and outputs to the API Resource being added to Alation Catalog. JSON Schema is very expressive, so only a subset of it is used here. We use:

-type to specific the type of a JSON field.

-required (optional) to note the input fields that are required (fields not in the list are not required). Not used on output of the Resource.

-properties to declare the contents of an object.

-items to declare the contents of a list. This can be a single item if the list is all of a single type, or a list of objects if the list is comprised of multiple types.

-examples (optional) to denote a list of examples for non-object, non-list types (string, number, character types).

JSON Schemas do not have to be written by hand! There are many tools to generate a schema given a sample piece of JSON, such as this one. For example, you can paste the output of the API you are documenting into the generator to create the JSON Schema needed. Take caution with sensitive data when taking this approach, as the contents of your sample piece of json will be used as example values.

Each field in the input to the API Resource as well as each field of the output will have its own page in the Catalog were sample values will be displayed along with logical metadata such as a title, description and custom fields.

Create an API Resource

This API allows you to create an API Resource by uploading a url, HTTP method, response type, a JSON Schema to model the input(s) to the API, as well as a Schema to model the output.

URL

POST /integration/v1/api_resource/**<HTTP\_method>**:**<url>**/
  • Replace <HTTP_method> with the HTTP method used to access your API Resource.
  • The trailing slash is important!
  • Replace <url> with the url or uri of your API Resource.

Sample Request Body

{
  "path": ["Data APIs", "Table", "Get table"],
  "response_type": "JSON",
  "input_schema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number"
      },
      "parent_schema": {
        "type": "string",
        "examples": ["schema_1", "revenue_schema"]
      }
    },
    "required": ["id"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "num_columns": {
        "type": "integer",
        "examples": [1, 46, 22]
      },
      "columns": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"  
            }
          }
        }
      },
      "datasource": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "id": {
            "type": "number"
          }
        }
      }
    }
  }
}
KeyRequiredValueType
pathYesA list of strings, where the last string in the list specifies the title of the API Resource, and each string to the left denotes the folder that the Resource belongs in. If a folder with the given path does not exist, it is created. Another way to explain the path, is that the first string in the list is the top-level folder, and each following string is a descendant folder.list of strings
response_typeNoThe type of data returned by the API. Examples: "JSON", "document", "text"string
input_schemaNoJSON Schema object describing the input(s) to the APIobject
output_schemaNoJSON Schema object describing the output of the APIobject

Headers

HTTP HeaderValue
TOKEN<your_token>
Content-Typeapplication/json

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

Object representing the created Resource.

{
  "id": "", "resource_url": "", "request_type": "", "response_type": "", "path": [...]
}

Code Example

import requests
import json

url = "https://ALATIONDOMAIN/integration/v1/api_resource/POST:https://RANDOMWEBSITE.com/v1/social-search/"

payload = json.dumps({
  "path": [
    "Example API Call",
    "Search Type",
    "Credit Search By Social"
  ],
  "response_type": "JSON",
  "input_schema": {
    "type": "object",
    "properties": {
      "body": {
        "type": "object",
        "properties": {
          "name": {
            "type": "object",
            "properties": {
              "first_name": {
                "type": "string",
                "examples": [
                  "John",
                  "Jane"
                ]
              },
              "middle_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string",
                "examples": [
                  "Doe"
                ]
              }
            },
            "required": [
              "first_name",
              "last_name"
            ]
          },
          "driverlicense": {
            "type": "string",
            "examples": [
              "DL123456789"
            ]
          },
          "ssn": {
            "type": "string",
            "examples": [
              "123-45-6789",
              "555-12-1234"
            ]
          }
        },
        "required": [
          "ssn",
          "name"
        ]
      }
    },
    "required": [
      "body"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "response": {
        "type": "object",
        "properties": {
          "full_name": {
            "type": "string",
            "examples": [
              "John Doe",
              "Jane Doe"
            ]
          },
          "ssn": {
            "type": "integer",
            "examples": [
              "123-45-6789"
            ]
          },
          "risk_score": {
            "type": "integer",
            "examples": [
              "123-45-6789"
            ]
          }
        }
      }
    }
  }
})
headers = {
  'token': 'TOKENHERE',
  'Content-Type': 'application/json'
}

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

print(response.text)

Retrieve an API Resource

URL

GET /integration/v1/api_resource/**<HTTP\_method>**:**<url>**/

Replace <HTTP_method> with the HTTP method used to access your API Resource.

Replace <url> with the url or uri of your API Resource.

Headers

HTTP HeaderValue
TOKEN<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

Object representing the Resource.

{
  "id": "", "resource_url": "", "request_type": "", "response_type": "", "path": [...]
}

Partially Update an API Resource

NOTE: If the path is changed, the given Resource will be moved to the new folder(s) specified. If the previous folder(s) become empty, they are deleted.

URL

PATCH /integration/v1/api_resource/**<HTTP\_method>**:**<url>**/

Replace <HTTP_method> with the HTTP method used to access your API Resource.

Replace <url> with the url or uri of your API Resource.

Sample Request Body

{
  "path": ["Data APIs", "Tables", "Get Table Version 2"],
  "response_type": "Text",
  "input_schema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number"
      }
    },
    "required": ["id"]
  }
}
KeyRequiredValueType
pathNoA list of strings, where the last string in the list specifies the title of the API Resource, and each string to the left denotes the folder that the Resource belongs in. If a folder with the given path does not exist, it is created. Another way to explain the path, is that the first string in the list is the top-level folder, and each following string is a descendant folder.list of strings
response_typeNoThe type of data returned by the API. Examples: "JSON", "document", "text"string
input_schemaNoJSON Schema object describing the input(s) to the APIobject
output_schemaNoJSON Schema object describing the output of the APIobject

Headers

HTTP HeaderValue
TOKEN<your_token>
Content-Typeapplication/json

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

Object representing the Resource updated.

{
  "id": "", "resource_url": "", "request_type": "", "response_type": "", "path": [...]
}

Update an API Resource

NOTE: If the path is changed, the given Resource will be moved to the new folder(s) specified. If the previous folder(s) become empty, they are deleted.

URL

PUT /integration/v1/api_resource/**<HTTP\_method>**:**<url>**/

Replace <HTTP_method> with the HTTP method used to access your API Resource.

Replace <url> with the url or uri of your API Resource.

Sample Request Body

{
  "path": [...],
  "response_type": "JSON"
  "output_schema": {...},
  "input_schema": {...}
}
KeyRequiredValueType
pathYesA list of strings, where the last string in the list specifies the title of the API Resource, and each string to the left denotes the folder that the Resource belongs in. If a folder with the given path does not exist, it is created. Another way to explain the path, is that the first string in the list is the top-level folder, and each following string is a descendant folder.list of strings
response_typeNoThe type of data returned by the API. Examples: "JSON", "document", "text"string
input_schemaNoJSON Schema object describing the input(s) to the APIobject
output_schemaNoJSON Schema object describing the output of the APIobject

Headers

HTTP HeaderValue
TOKEN<your_token>
Content-Typeapplication/json

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

Object representing the Resource updated.

{
  "id": "", "resource_url": "", "request_type": "", "response_type": "", "path": [...]
}

Delete an API Resource

NOTE: This will mark the given Resource deleted. If the same Resource is created again or updated, the Resource's description and custom field values will be restored.

URL

DELETE /integration/v1/api_resource/**<HTTP\_method>**:**<url>**/

Replace <HTTP_method> with the HTTP method used to access your API Resource.

Replace <url> with the url or uri of your API Resource.

Headers

HTTP HeaderValue
TOKEN<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 204

Body

Object representing the Resource deleted.

{
  "id": "", "resource_url": "", "request_type": "", "response_type": "", "path": [...]
}

Error Response

Invalid Token

Status: 401 UNAUTHORIZED

Body

{
   "detail": "Authentication failed"
}

Missing Token Header

Status: 401 UNAUTHORIZED

Body

{
    "detail": "Authentication credentials were not provided."
}

NOTE: The error responses are common to all of the requests above.