Golden API

Trazadera Golden provides a full API based on REST and OpenAPI definition.

The Golden API has predictable resource-oriented URLs, accepts URL parameters, request parameters and request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Golden API is published in OpenAPI JSON format. Always check the API version before consuming it.

You can download the Golden OpenAPI JSON definition from several places:

The trazadera-golden-openapi public project in github contains the API definition, resources to generate the OpenAPI Java client, and a sample usage program. This is the place to start interaction with the Golden API, although the API version might be outdated.
. You should download the API version running for your production environment, as described later in Retrieving API Version and OpenAPI definition.

Getting Started

In a nutshell, you need the API <GOLDEN_URL> and the access <GOLDEN_TOKEN> to start using the Golden API. Your administrator or Trazadera Support will provide you with this information.

Always remember to replace <GOLDEN_URL> and <GOLDEN_TOKEN> with the right information.

The provided examples will assume that we have declared these variables in the command line. The API client returns an error if an invalid URL is used. Additionally, the API will return an error when attempting to access an operation without proper authentication using an access token.

CODE

export GOLDEN_URL="https://foo.trazadera.net"
export GOLDEN_TOKEN="golden:AveryLongToken"

Most of the Golden API requires to be authenticated. To get started, run this API call to /api/security/whoami to double-check that your URL is right, as this specific operation allows to be called with or without authentication.

BASH

curl -X 'GET' "${GOLDEN_URL}/api/security/whoami" \
    -H 'accept: */*' \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

If you have provided a valid <GOLDEN_TOKEN> you will get a response similar to this one. It contains the basic authentication and authorization information for the provided access token. The permissions have been excerpted for brevity.

JSON

{
  "token": "golden:***",
  "id": "t-***",
  "role": "myrole",
  "permissions": {
    "security.user.save": "DENY",
    "event.view": "DENY",
    "golden.upsertRecord": "DENY"
  },
  "name": "CRM",
  "type": "ACCESS_TOKEN"
}

However, if you provided an invalid <GOLDEN_TOKEN>, or you don’t include the Authorization header, you will get a response indicating the you are not authenticated.

CODE

{
  "type": "NONE"
}

Authentication

The Golden API uses access tokens to authenticate requests. Your Golden administrator can manage your API keys, including creation, renewal or deletion.

Your API keys carry many privileges, so be sure to keep them secure

Considerations for authenticating against the Golden API:

Authentication to the API is performed via the Authentication: Bearer header.
You will have to include the header and the token for every API request.
Remember that a valid Golden API token will always contain the golden: prefix.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
API requests without authentication will fail, except when accessing authentication endpoints, which do not require prior authentication.

Success and Error messages

The Golden API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Code	Result	Meaning
`200`	SUCCESS	Expect JSON content in the response.
`400`	ERROR	Invalid parameters provided.
`401`	ERROR	Authentication required. You have not provided a token, or the token is invalid.
`403`	ERROR	Not authorized. Your role does not allow to execute the operation.
`404`	ERROR	Resource not found. You are trying to access a resource that does not exist.
`409`	ERROR	Invalid object status. The object you are accessing is not in the right status.
`500`	ERROR	Unexpected system error.

Your client should leverage both HTTP response code and informational messages

The response content is encoded in the application/json format. It will include zero, one, or multiple success or error messages, following the format below. A successful response will contain informational messages, while an error response will include error messages.

JSON

$ curl -X 'GET' "${GOLDEN_URL}/api/invalid"  \
    -H 'accept: */*' \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"
    
{"errors":["No static resource api/invalid."]}

Retrieving the API Version and OpenAPI definition

The API includes an endpoint to retrieve the current version. You can obtain the running version of the Golden API by making a request to /api/configuration/version. It is recommended to always use an API version that aligns with your production environment.

BASH

curl -X 'GET' "${GOLDEN_URL}/api/configuration/version"  \
    -H 'accept: */*' \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"
    
{"version":"16-SNAPSHOT"}

The OpenAPI definition is an enterprise standard for API specifications. The Golden API is defined using the OpenAPI format. You can retrieve the current OpenAPI definition for your production environment by making a request to /api/system/openapi.

BASH

curl -X 'GET' "${GOLDEN_URL}/api/configuration/openapi"  \
    -H 'accept: */*' \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

The response will be a JSON object in OpenAPI format (excerpt shown below). For more details on the OpenAPI specification, refer to https://swagger.io/specification/.

CODE

{
  "openapi": "3.0.1",
  "info": {
    "title": "GOLDEN-API",
    "description": "Trazadera Golden API",
    "contact": {
      "name": "Contact",
      "url": "https://www.trazadera.com",
      "email": "[email protected] "
    },
    "license": {
      "name": "Legal Notice",
      "url": "https://www.trazadera.com"
    },
    "version": "16-SNAPSHOT"
  },
  ...
}

API Structure

The Golden API is organized into modules, represented by OpenAPI tags, which group related functionalities under the same concept (e.g., users or tables).

The most significant module is golden, which contains methods for managing Golden Records.

These are the functional modules available in Golden API:

golden: manages Golden Records
entity: manages Entities.
resource: manages Resources.
table: manages Tables.
metric: manages Metrics.

These are the system modules aimed at system administration:

security: authentication, user and token management.
task: task management.
event: event management.
file: file management.
configuration: configuration (user, system) management, version and OpenAPI.

Roles and Authorization

Your token is associated a to certain role, as defined in the Security section. After a successful authentication, every API call is authorized against the permissions associated to your role.

You will get a HTTP 403 error if you don’t have the right permissions when calling the API

Make sure to understand these security guidelines:

Always enforce the Least Privilege Principle. That means to grant the role with the least privileges that is needed for your needs.
Specifically, try to avoid granting the ADMIN role to a token. Although tokens can be revoked, they must be stored somewhere and could be stolen.
On the other hand, physical users will authenticate against the web interface using credentials and additional security enforcement methods, such a 2-Factor Authentication (2FA) or Single Sign-On (SSO).
Permissions are incrementally granted:
- The USER role is aimed at reading data.
- The STEWARD role is aimed at reading and writing data.
- The ADMIN role is aimed at reading and writing data and configuration.
Certain operations are limited to you own, eg. changing the password. Only the user is able to change its own password; the administrator can only reset an user’s password. This is a security enforcement to avoid impersonation.
Certain operations are limited to physical users, eg. changing your user information only makes sense to users.