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.
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}`}
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"
}
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=="
}
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.
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.
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=="
}
}
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.
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=="
}]
}
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 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).