Requirements

• Please have your Alation Admin enable this feature by following the steps from this guide in the Alation Help Center.
• Note: Only admin users can create or update API resources using this API.

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 the following elements:

• URL
• HTTP method
• Response type
• JSON schema describing the input(s) to the API resource
• 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 (API resources are soft-deleted and 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 specify 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 jsonschema.net. 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 JSON schema to model the output.

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.
• The trailing slash is important!

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"
          }
        }
      }
    }
  }
}

Headers

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

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

Replace with the URL or URI of your API resource.

Headers

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

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

Replace 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"]
  }
}

Headers

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 esource will be moved to the new folder(s) specified. If the previous folder(s) become empty, they are deleted.

URL

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

Replace with the URL or URI of your API resource.

Sample Request Body

{
  "path": [...],
  "response_type": "JSON"
  "output_schema": {...},
  "input_schema": {...}
}

Headers

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

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

Replace with the URL or URI of your API resource.

Headers

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 API 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.