REST API

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

Every API request requires an Accept header. 

• This header is used to identify the version of the API. 
• Its format is specified in the API doc for each endpoint. Usually, it's application/vnd.yellowfin.api-v1+json
• The API is backwards compatible. Requests for a v1 resource will work even when the current API version in a Yellowfin instance is v2. 

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

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

• Every link represents related resources which the user has access to.
• The client should use the link in the "href" attribute to access the resource rather than hard coding it in application code.
• The "options" array lists the HTTP methods which the user is authorised to use with the link. For example, the example above tells us that the user can read the comments list (GET) or create a new one (POST). They cannot delete all comments, which is why DELETE is not available in the "comments" link.

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.
   
   

Access Tokens 

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

• use the POST operation
• use the URL of the access token endpoint
• use the same headers as the refresh token request
  • the Authorization header must specify a refresh token, with a property named token

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.

• Use the POST method and set the URL to /login-tokens/create-sso-token
• Requisite headers should be set:
  
  
  
  
• The request body should be set as raw JSON 
  
  
  

• The response contains a login token and the API endpoint for terminating the session.
  
  
  
  

• The token may be used for logging into the Yellowfin Web UI or the JavaScript API. See Redirecting to Yellowfin with the Login Token.

Troubleshooting

• Clock Skew — This is one of the most commonly-encountered errors. It is because the timestamp in the Authorization header is not in sync with the server time. There is a +/- 5-minute tolerance but if it falls outside that window, the API will respond with an error.
  
  
  

• Token expiry — The API responds with an error when an expired access token is used.
  
  
  
  

• Authentication failure — This could occur because of an invalid username or password.
  
  
  
  

• Unknown version — If an incorrect version of the API is specified in the Accept header.
  
  
  
  

• Licencing error — Content services such as GET/stories/uuid, are only available when a server licence is present. If not, the API will return a 401 Unauthorized error. 
  
  
  

• CORS — This is generally not a problem for the REST API because CORS applies only to browsers. A web browser is not a recommended REST client as it is not easy to securely store tokens.

• SSO Errors — Ensure that credentials and org reference are correct. If noPassword authentication is being used, ensure that it has been enabled on the server. This is done by inserting a record into the Configuration table and restarting Yellowfin.
  
  INSERT INTO Configuration values (1, 'SYSTEM', 'SIMPLE_AUTHENTICATION', 'TRUE');
  
  
  
  

• Error 500 Internal Server Error — This is a generic error message which indicates that something went wrong on the server. Contact support with the error trace in the server logs for more information.

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