Conventions

Throughout the documentation you will regularly encounter the following variables. These represent user-specific values that should be replaced when attempting any of the calls using your account.

Variable Description Example
${API_HOST} Base hostname of the API api.tacc.utexas.edu
${API_VERSION} Version of the API endpoint v2.2.8
${API_USERNAME} Username of the current user nryan
${API_KEY} Client key used to request an access token from the Tapis Auth service hZ_z3f4Hf3CcgvGoMix0aksN4BOD6
${API_SECRET} Client secret used to request an access token from the Tapis Auth service gTgpCecqtOc6Ao3GmZ_FecVSSV8a
${API_TOKEN} Client unique identifier of an application requesting access to Tapis Auth service de32225c235cf47b9965997270a1496c

JSON Notation

Show JSON notation
{
    "active": true,
    "created": "2014-09-04T16:59:33.000-05:00",
    "frequency": 60,
    "id": "0001409867973952-5056a550b8-0001-014",
    "internalUsername": null,
    "lastCheck": [
      {
        "created": "2014-10-02T13:03:25.000-05:00",
        "id": "0001412273000497-5056a550b8-0001-015",
        "message": null,
        "result": "PASSED",
        "type": "STORAGE"
      },
      {
        "created": "2014-10-02T13:03:25.000-05:00",
        "id": "0001411825368981-5056a550b8-0001-015",
        "message": null,
        "result": "FAILED",
        "type": "LOGIN"
      }
    ],
    "lastSuccess": "2014-10-02T11:03:13.000-05:00",
    "lastUpdated": "2014-10-02T13:03:25.000-05:00",
    "nextUpdate": "2014-10-02T14:03:15.000-05:00",
    "owner": "systest",
    "target": "demo.storage.example.com",
    "updateSystemStatus": false,
    "_links": {
        "checks": {
            "href": "https://api.tacc.utexas.edu/monitor/v2/0001409867973952-5056a550b8-0001-014/checks"
        },
        "notifications": {
            "href": "https://api.tacc.utexas.edu/notifications/v2/?associatedUuid=0001409867973952-5056a550b8-0001-014"
        },
        "owner": {
            "href": "https://api.tacc.utexas.edu/profiles/v2/systest"
        },
        "self": {
            "href": "https://api.tacc.utexas.edu/monitor/v2/0001409867973952-5056a550b8-0001-014"
        },
        "system": {
            "href": "https://api.tacc.utexas.edu/systems/v2/demo.storage.example.com"
        }
    }
}

Javascript dot notation will be used to refer to individual properties of JSON objects. For example, consider the following JSON object.

  • active refers to the top level active attribute in the response object.
  • lastCheck.[].result generically refers to the result attribute contained within any of the objects contained in the lastCheck array.
  • lastCheck.[0].result specifically refers to the result attribute contained within the first object in the lastCheck array.
  • _links.self.href refers to the href attribute in the checks object within the _links object.

Versioning

The current major version of Tapis is given in the URI immediately following the API resource name. For example, if the endpoint is https://api.tacc.utexas.edu/jobs/v2/, the API version would be v2. The current major version of Tapis is v2. (Full version: 2.2.23)

Special Character Handling

In certain situations, usually where file system paths and names are involved in some way, Tapis will generate sanitized object names (“slugs”) to make them safe to use. Slugs will be created on the fly by applying the following rules:

  1. Lowercase the string
  2. Replace spaces with a dash
  3. Remove any special characters and punctuation that might require encoding in the URL. Allowed characters are alphanumeric characters, numbers, underscores, and periods.

Secure communication

Tapis uses SSL to secure communication with the clients. If HTTPS is not specified in the request, the request will be redirected to a secure channel.

Requests

The Tapis API is based on REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. The API uses appropriate HTTP verbs for each action whenever possible.

Verb Description
GET Used for retrieving resources
POST Used for creating resources
PUT Used for manipulating resources or collections
DELETE Used for deleting resources

Common API query parameters

Several URL query parameters are common across all services. The following table lists them for reference

Name Values Purpose
offset integer (zero based) Skips the first offset results in the response
limit integer Limits the number of responses to, at most, this number
pretty boolean If true, pretty prints the response. Default false
naked boolean If true, returns only the value of the result attribute in the standard response wrapper
filter string A comma-delimited list of fields to return for each object in the response. Each field may be referenced using JSON notation

Experimental query parameters

Starting with the 2.1.10 release, two new query parameters have been introduced into the jobs API as an experimental feature. The following table lists them for reference

Name Values Purpose
sort asc,desc The sort order of the response. asc by default
sortBy string The field by which to sort the response. Any field present in the full representation of the resource that you are querying is supported. Multiple values are not currently supported

Responses

All data is received and returned as a JSON object.

Response Details

{
    "status": "error",
    "message": "Permission denied. You do not have permission to view this system",
    "version": "2.1.16-r8228",
    "result": {}
}

Apart from the response code, all responses from Tapis are in the form of a json object. The object takes the following form.

Key Value Type Value Description
status string User will see message=null on status "success"
message string A short description of the cause of the error
result object,array The JSON response object or array
version string The current full release version of Tapis. Ex “2.1.16-r8228”

Here, for example, is the response that occurs when trying to fetch information for system to which you do not have access:

Naked Responses

In situations where you do not care to parse the wrapper for the raw response data, you may request a naked response from the API by adding naked=true in to the request URL. This will return just the value of the result attribute in the response wrapper.

naked=true

{
  "id" : "data.iplantcollaborative.org",
  "name" : "CyVerse Data Store",
  "type" : "STORAGE",
  "description" : "CyVerse's petabyte-scale, cloud-based data management service.",
  "status" : "UP",
  "public" : true,
  "lastUpdated" : "2017-10-10T00:00:00.000-05:00",
  "default" : true,
  "_links" : {
    "self" : {
      "href" : "https://agave.iplantc.org/systems/v2/data.iplantcollaborative.org"
    }
  }
}

naked=false

{
  "status" : "success",
  "message" : null,
  "version" : "2.2.8-rff32e62",
  "result" : [ {
    "id" : "data.iplantcollaborative.org",
    "name" : "CyVerse Data Store",
    "type" : "STORAGE",
    "description" : "CyVerse's petabyte-scale, cloud-based data management service.",
    "status" : "UP",
    "public" : true,
    "lastUpdated" : "2017-10-10T00:00:00.000-05:00",
    "default" : true,
    "_links" : {
      "self" : {
        "href" : "https://agave.iplantc.org/systems/v2/data.iplantcollaborative.org"
      }
    }
  } ]
}

Formatting

By default, all responses are serialized JSON. To receive pre-formatted JSON, add pretty=true to any query string.

Timestamps

Timestamps are returned in ISO 8601 format offset for Central Standard Time (-05:00) YYYY-MM-DDTHH:MM:SSZ-05:00.

Cross Origin Resource Sharing (CORS)

Many modern applications choose to implement client-server communication exclusively in Javascript. For this reason, Tapis provides cross-origin resource sharing (CORS) support so AJAX requests from a web browser are not constrained by cross-origin requests and can safely make GET, PUT, POST, and DELETE requests to the API.

Hypermedia

{
    "associationIds": [],
    "created": "2013-11-16T11:25:38.900-06:00",
    "internalUsername": null,
    "lastUpdated": "2013-11-16T11:25:38.900-06:00",
    "name": "color",
    "owner": "nryan",
    "uuid": "0001384622738900-5056a550b8-0001-012",
    "value": "red",
    "_links": {
        "self": {
            "href": "https://api.tacc.utexas.edu/meta/v2/data/0001384622738900-5056a550b8-0001-012"
        },
        "owner": {
            "href": "https://api.tacc.utexas.edu/profiles/v2/nryan"
        }
    }
}

Tapis is a fully descriptive hypermedia API. Given any point, you should be able to run API through the links provided in the _links object in each resource representation. The following user metadata object contains two referenced objects. The first, self is common to all objects, and contains the URL of that object. The second, owner contains the URL to the profile of the user who created the object.