jsreport provides plain HTTP rest based API for rendering and CRUD
jsreport API can be split into two main use cases:
The following two sections are describing these main use cases in detail.
The jsreport studio uses the same API exposed to you. In case you are missing something in the documentation, you can open F12 browser tools and see what is happening in the network tab.
Invoking the report rendering process is the most commonly used API method. The next snippet shows the service endpoint URL as well as the body schema. Options and data fields are optional.
POST:https://jsreport-host/api/report
Headers: Content-Type: application/json
BODY:{ "template": { "name" : "my template" }, "data" : { ... }, "options": { "reports": { "save": true } } }
In the most typical case, you just need to specify template name (or shortid) and input data. The template name property needs to be a unique template name. In the case you use multiple folders it's recommended to pass the full path instead of the name. For example
{
"template": { "name": "/myfolder/mytemplate" }"
"data": {}
}
You may want to override just some attributes of the template. This is easy because all the request attributes are merged into the stored template before evaluation. If you want to for example just change the template recipe to html you can do it with the following request body.
{
"template": {
"name": "myTemplate",
"recipe": "html"
},
"data" : { ... },
}
The template doesn't necessarily need to be stored inside jsreport templates store and it can be fully defined in the request body. In this case, you need to specify at least the required attributes recipe, engine, and content. The following snippet shows how to define such a request body.
{
"template": {
"content" : "Hello world {{name}}",
"recipe": "chrome-pdf",
"engine": "handlebars",
"chrome": {
"landscape": true
}
},
"data" : { ... },
}
The valid template properties can be inspected in the jsreport studio. You can define the template to your needs, run it, and open the profile. Then click the very first node and use "Open Request". This provides you JSON you can replicate in your API call.
Another option to inspect the valid template properties is to use OData metadata definition. This can be reached at http://jsreport-host/odata/$metadata
The template typically references additional entities like scripts or additional templates for pdf utils operations. When you don't want to use the store, you need to specify the full entities' content instead of the references. This is specific for every extension or recipe and you should read the API section of a particular extension's documentation.
The rendering timeout specified in the configuration reportTimeout can be overridden in the API call. This possibility needs to be opted in using configuration enableRequestReportTimeout=true. Then use options.timeout in the request body.
{
"template": { ... },
"options": { "timeout": 30000 }
}
You can change the Content-Disposition response header thus the file name browser displays during download using the request property options[reportName]
{
"template": { ... },
"options": { "reportName": "myreport" }
}
The file extension adds jsreport depending on the content type of the report being generated. For example chrome-pdfproduces "myreport.pdf" in this case.
In case you want full control over this response header you can specify options['Content-Disposition'] in the request body and override the defaults.
There are also API wrappers for popular platforms which can be used to invoke report rendering.
Querying and CRUD API in jsreport is based on OData protocol. You can use it to query or CRUD programmatically any entity that jsreport server contains. The Odata defines some basic standards jsreport follows, here are some examples of the most common calls.
Get all entity types
Get list of templates' names
Get a script with specific name
GET:http://jsreport-host/odata/scripts?$filter=name eq 'myscript'
Get an assets in a specific folder
GET:http://jsreport-host/odata/assets?$filter=folder/shortid eq 'abc'
Create a template
POST: http://jsreport-host/odata/templates
Headers: Content-Type: application/json
BODY:{ "name":"demo", "recipe":"chrome-pdf", "engine":"handlebars", "content":"<h1>sample content</h1>" }
Read a template by id
Update template property
PATCH: http://jsreport-host/odata/templates(WOIzhZdfjj7rRRO2)
Headers: Content-Type: application/json
BODY:send the properties that you want to change{ "content": "updated content" }
Delete a template
DELETE: http://jsreport-host/odata/templates(UCV8p6iVIzR6pEz8)
Folders are entities just like templates and you can use the same odata calls for them.
You can for example list all folders using
Get templates in specific folder
GET:http://jsreport-host/odata/templates?$filter=folder/shortid eq 'foo'
Get templates in the root folder
GET:http://jsreport-host/odata/templates?$filter=folder eq null
Create a template in specific folder
POST:http://jsreport-host/odata/templates{ "name": "template name", "engine": "none", "recipe": "html", "folder": { "shortid": "foldershortid" } }
When jsreport server has authentication extension enabled or when using jsreportonline you need to add authentication header to all API requests. The header is based on basic http authentication so you should be able to authenticate easily from any platform.
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Where the hash is based on username and password:base64(username:password)
Check authentication extension docs for more details about different authentication options
There is a public endpoint http://jsreport-host/api/ping which you can use to check if the jsreport is running. This endpoint isn't behind the authentication, so you can use it from your load-balancer or docker health check.