Page History
Table of Contents
| Info | ||
|---|---|---|
| ||
The full documentation of the current REST services is available in our external developer site. |
Key Concepts
The REST API is available under the /api namespace. For example, https://yellowfin.myapp.com/api/stories
...
- 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:
- Logging in — Creating a new refresh token.
- Access tokens — Used to authorise a user access to REST API resources.
- Logging out — Deleting a Refresh Token.
- Requesting Resources — Actually retrieving data using the REST API.
Logging In (Creating a Refresh Token) Anchor login login
| login | |
| login |
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.
...
| Note |
|---|
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 Anchor accesstoken accesstoken
| accesstoken | |
| accesstoken |
Creating an access token is a very similar process to creating a refresh token. To create one:
...
| Tip |
|---|
| 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) Anchor logout logout
| logout | |
| logout |
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.
...
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 Anchor reqresources reqresources
| reqresources | |
| reqresources |
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.
...
- 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.
...