The full documentation of the current REST services is available in our external developer site.
Click here to access it.

Key Concepts

The REST API is available under the /api namespace. For example, https://yellowfin.myapp.com/api/stories

The suite includes RPC calls as well, in the /api/rpc namespace.

Every API request requires an Authorization header. Its format is
YELLOWFIN ts=1600224140615 nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf token=securityToken

ComponentDescription
YELLOWFINCustom authentication scheme
tsThe time in milliseconds from the Unix epoch 00:00:00 UTC on 1 January 1970. This is the current time in the program which calls the API. Every programming language has a way to get the current time in this format.
nonceA random UUID generated by the client.
tokenA security token used for authenticating the user and authorizing access to the resource. 


Every API request requires an Accept header

There are two security tokens which are key for consuming the API.

TokenDescription
RefreshThis is an opaque security token obtained on login. Refresh Tokens do not expire and may be securely saved in the client application for obtaining access tokens.
AccessThis is a JSON Web Token (JWT) which expires after 20 minutes. An access token needs to be sent in the Authorization header of nearly every API request. On expiry, the client application can use the refresh token to get a new access token.


Every API response will have one or more "_links" objects.


Using the API

REST API calls may be grouped into the following categories:

  1. Logging in — Creating a new refresh token.
  2. Access tokens — Used to authorise a user access to REST API resources.
  3. Logging out — Deleting a Refresh Token.
  4. Requesting Resources — Actually retrieving data using the REST API.

Logging In (Creating a Refresh Token) 

Rather than a session, a refresh token is used to identify a user. A consumer must create a refresh token and obtain an access token before they can use other REST endpoints. Creating a refresh token can be thought of as a login process.

  1. Use the HTTP operation POST. Requests that create any kind of resource will always use a POST operation. In this case, a refresh token is being created.



  2. Enter the URL of the refresh token endpoint. A valid URL will always have either a name (eg, http://yellowfin.myapp.com/api/...) or an IP address (eg, http://127.0.0.1/api/...). It may have a port specified (eg, http://yellowfin.myapp.com:8080/api/...).



  3. Set the mandatory request headers. Refer to the REST API for a full list of headers required to make an API request.



  4. The request body contains a JSON representation of a username and password. Make sure that the body is sent as raw JSON.



    The response of this request will contain the newly-created refresh token, and under the _embedded property, an access token.


The client application should securely store these tokens. It should also store the "self" link as it will be needed for logging out.

Access Tokens 

Creating an access token is a very similar process to creating a refresh token. To create one:




The refresh token response provides an access token to make it easier to start consuming the API after login.


Logging Out (Deleting a Refresh Token) 

The response of the POST/refresh-tokens request will contain the information required to effectively "log out" of the REST API — a call to delete that refresh token. The response of the POST/refresh-tokens request contains a _links property. 



The options array in the "self" link lists which operations can be performed on the new refresh token. There should only be one — "DELETE". Calling DELETE /refresh-tokens will effectively log the user out of the REST API.

Note that a valid access token is required to perform this operation. It must be included in the token property of the Authorization header.

Requesting Resources 

To make a resource request, the API client must have a valid access token. Please consult the API doc for the headers that need to be specified for each endpoint, along with mandatory and optional parameters.

Web SSO

A popular use-case for the API is Web SSO. A couple of API endpoints are available for generating a login token. The generated token can be used to login to Yellowfin’s browser interface. The simplest way to do this is to use the RPC endpoint POST /login-tokens/create-sso-token.


Troubleshooting





The full documentation of the current REST services is available in our external developer site. Click here to access it.