The full documentation of the current REST services is available in our external developer site. |
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
Component | Description |
---|---|
YELLOWFIN | Custom authentication scheme |
ts | The 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. |
nonce | A random UUID generated by the client. |
token | A security token used for authenticating the user and authorizing access to the resource. |
Every API request requires an Accept header.
application/vnd.yellowfin.api-v1+json
There are two security tokens which are key for consuming the API.
Token | Description |
---|---|
Refresh | This 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. |
Access | This 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.
"href"
attribute to access the resource rather than hard coding it in application code."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.REST API calls may be grouped into the following categories:
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.
_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. |
Creating an access token is a very similar process to creating a refresh token. To create one:
token
The refresh token response provides an access token to make it easier to start consuming the API after login. |
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.
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.
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.
Accept
header.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.The full documentation of the current REST services is available in our external developer site. Click here to access it.