API Reference

The Vaas App API is structured around REST. Resources can be created and retrieved accordingly. It makes use of intuitive HTTP methods in modelling the API behavior. The API is simple to use and can be consumed easily in less than 5 minutes.

Base URL

https://vaasapp.co

Postman Collection

https://documenter.getpostman.com/view/9506038/TVzNHK6P

Authentication

The Vaas App API uses Basic authentication for authorizing API clients and users to create and retrieve data visualizations. The required credentials for creating the basic authorization token are your signup email and password.

If you are working in the NodeJS environment, you can easily create the basic authorization token for your request using the code below:
var username = '[email protected]';
var password = '347jdlfjdA?';
var authToken = Buffer.from(`${username}:${password}`, 'base64');
var headers = {'Authorization': `Basic ${authToken}`}

Create new visualization

Method: POST

URL: /api/visualizations/

Authorization Header: Yes

Creating a new data visualization is quite seamless. You can create a new visualization using a data object or referencing the url where the data is stored. However, the data must be an array of objects containing the fields that are required to create a data visualization.

It is required that the x-axis and y-axis for the chart be selected and must be in the data so as to enable a correct creation of the chart.


The file types supported using data urls are .json and .csv files at the moment. Any other file types would be rejected.

You can select the chart type you want. The supported chart types are: bar, pie and line and it defaults to bar chart

Creating a visualization using a data url.
var dataObject = {
    "title":"Graph of air travel in Spain",
    "xAxisField":"Month",
    "yAxisField":"1958",
    "dataUrl": "https://people.sc.fsu.edu/~jburkardt/data/csv/airtravel.csv"
    "chartType":"pie"
}
Creating a visualization using raw data
var dataObject = {
    "title":"Graph of air travel in Spain",
    "xAxisField":"Month",
    "yAxisField":"1959",
    "data": [{"1958":"340","1959":"360","1960":"417","Month":"JAN"},{"1958":"318","1959":"342","1960":"391","Month":"FEB"},{"1958":"362","1959":"406","1960":"419","Month":"MAR"},{"1958":"348","1959":"396","1960":"461","Month":"APR"},{"1958":"363","1959":"420","1960":"472","Month":"MAY"},{"1958":"435","1959":"472","1960":"535","Month":"JUN"},{"1958":"491","1959":"548","1960":"622","Month":"JUL"},{"1958":"505","1959":"559","1960":"606","Month":"AUG"},{"1958":"404","1959":"463","1960":"508","Month":"SEP"},{"1958":"359","1959":"407","1960":"461","Month":"OCT"},{"1958":"310","1959":"362","1960":"390","Month":"NOV"},{"1958":"337","1959":"405","1960":"432","Month":"DEC"}]
    "chartType":"bar"
}

Parameters

titlerequired
The title of the chart that would be created. It's a string

xAxisFieldrequired
The field name that would be used as the x-axis for the visualization that would be created. This field must exist in the data if not the visualization creation request would be rejected.

yAxisFieldrequired
The field name that would be used as the y-axis for the visualization that would be created. This field must exist in the data if not the visualization creation request would be rejected.

dataoptional
An array of objects containing the data that would be visualized. The objects must have the x-axis and y-axis fields as part of their data fields if not the data would be rejected. This field is used when a developer has their raw data already parsed and cleaned else, the dataUrl field is used.

dataUrloptional
A HTTP url containing the download url for the file to be visualized. It can be CSV or JSON file. This field can be ignored if the data field is provided. Also, if it's a JSON file, it must be an array of JSON objects.

chartTypeoptional
The type of chart the user wants to create. It can be any of line, bar or pie. It defaults to bar

If a visualization is successfully created, it returns and object of the visualization id, created field and the visualization image url.
{
    "vizId":"5fea5e3133716c3a504410df",
    "created": true,
    "vizImageUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAu4AAALuCAYAAADxHZPKAAAgAElEQVR4Xu29faxs53Xe9
+5zSIr6sBinSQnFNkgxLgQEKtJIcF2qsERLRp0WTQ1bhSQLtkjxcniRBg0aqfBH5YikAkgB3NJObaHgnXsYkm1hMyqBxCjqGDAlURZMFbbhImWB2m0oMnBpyfmw=="
}

Response fields

vizId
The unique identification string for the created visualization.

created
A boolean reinforcing the fact that the visualization was created successfully.

vizImageUrl
The raw image data url that can be saved as a file. Presently it is a raw data url since the AWS security side of things have not been rectified and that's why it's not being saved as an AWS S3 file.

Retrieve a single single visualization

Method: GET

URL: /api/visualizations/:vizId

Authorization Header: Yes

A request to the endpoint with a valid visualization id returns the visualization object with all its data. If the visualization with the provided ID does not exist, it returns a 404 response.

Parameters

vizIdrequired
The unique identification string for the created visualization. Example is: `5fea5e33433716c3a504410ed`. It should be part of the request URL.

{data:
visualization:{
    "userId":"5fea5e33433716c3a504410df",
    "_id":"5fea5e33433716c3a504410ed",
    "title":"Graph of air travel in Spain",
    "xAxisField":"Month",
    "yAxisField":"1959",
    "data": [{"1958":"340","1959":"360","1960":"417","Month":"JAN"},{"1958":"318","1959":"342","1960":"391","Month":"FEB"},{"1958":"362","1959":"406","1960":"419","Month":"MAR"},{"1958":"348","1959":"396","1960":"461","Month":"APR"},{"1958":"363","1959":"420","1960":"472","Month":"MAY"},{"1958":"435","1959":"472","1960":"535","Month":"JUN"},{"1958":"491","1959":"548","1960":"622","Month":"JUL"},{"1958":"505","1959":"559","1960":"606","Month":"AUG"},{"1958":"404","1959":"463","1960":"508","Month":"SEP"},{"1958":"359","1959":"407","1960":"461","Month":"OCT"},{"1958":"310","1959":"362","1960":"390","Month":"NOV"},{"1958":"337","1959":"405","1960":"432","Month":"DEC"}]
    "chartType":"bar"
    "vizImageUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAu4AAALuCAYAAADxHZPKAAAgAElEQVR4Xu29faxs53Xe9
+5zSIr6sBinSQnFNkgxLgQEKtJIcF2qsERLRp0WTQ1bhSQLtkjxcniRBg0aqfBH5YikAkgB3NJObaHgnXsYkm1hMyqBxCjqGDAlURZMFbbhImWB2m0oMnBpyfmw=="
}
}

Response fields

userId
Your unique identification string on the platform

_id
The unique identification string for the created visualization.

title
The title of the visualization.

xAxisField
The pre-selected x-axis field of the visualization

yAxisField
The pre-selected y-axis field of the visualization

chartType
The pre-selected chart type for the visualization

data
The parsed and cleaned data that was uploaded by the user.

vizImageUrl
The raw image data url that can be saved as a file. Presently it is a raw data url since the AWS security side of things have not been rectified and that's why it's not being saved as an AWS S3 file.

Retrieve all visualizations.

Method: GET

URL: /api/visualizations/

Authorization Header: Yes

A request to the endpoint returns an array of visualizations already created by you and if no exists, it returns an empty array of visualizations

{data:
visualizations:[{
    "userId":"5fea5e33433716c3a504410df",
    "_id":"5fea5e33433716c3a504410ed",
    "title":"Graph of air travel in Spain",
    "xAxisField":"Month",
    "yAxisField":"1959",
    "data": [{"1958":"340","1959":"360","1960":"417","Month":"JAN"},{"1958":"318","1959":"342","1960":"391","Month":"FEB"},{"1958":"362","1959":"406","1960":"419","Month":"MAR"},{"1958":"348","1959":"396","1960":"461","Month":"APR"},{"1958":"363","1959":"420","1960":"472","Month":"MAY"},{"1958":"435","1959":"472","1960":"535","Month":"JUN"},{"1958":"491","1959":"548","1960":"622","Month":"JUL"},{"1958":"505","1959":"559","1960":"606","Month":"AUG"},{"1958":"404","1959":"463","1960":"508","Month":"SEP"},{"1958":"359","1959":"407","1960":"461","Month":"OCT"},{"1958":"310","1959":"362","1960":"390","Month":"NOV"},{"1958":"337","1959":"405","1960":"432","Month":"DEC"}]
    "chartType":"bar"
    "vizImageUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAu4AAALuCAYAAADxHZPKAAAgAElEQVR4Xu29faxs53Xe9
+5zSIr6sBinSQnFNkgxLgQEKtJIcF2qsERLRp0WTQ1bhSQLtkjxcniRBg0aqfBH5YikAkgB3NJObaHgnXsYkm1hMyqBxCjqGDAlURZMFbbhImWB2m0oMnBpyfmw=="
}]
}

Response fields

userId
Your unique identification string on the platform

_id
The unique identification string for the created visualization.

title
The title of the visualization.

xAxisField
The pre-selected x-axis field of the visualization

yAxisField
The pre-selected y-axis field of the visualization

data
The parsed and cleaned data that was uploaded by the user.

chartType
The pre-selected chart type for the visualization

vizImageUrl
The raw image data url that can be saved as a file. Presently it is a raw data url since the AWS security side of things have not been rectified and that's why it's not being saved as an AWS S3 file.

Error responses

Error responses span across the 400 to 599 HTTP status codes. Requests to the API server can end up coming back as errors and it is important that a prospective developer is aware of how all errors on the platform are returned. Error responses are returned as follows across the API:

{errors: [{
    "reason":"Invalid authorization header", // reason for error
    "field":null, // field responsible for the error
    "code":"4xx", // code is mapped from the HTTP status code and can either be '4xx' or '5xx'
    }]
}

The errors field in an error response object is an array of error objects which implies that multiple errors can exist in a single request (especially for request body data validation).