API
API
A REST API is provided to facilitate interacting with some aspects of ART in a programmatic fashion, as opposed to using the browser.
Base URL
The base URL for all api calls is /art/api/
Responses
Calls to the api will result in responses that contain an ApiResponse object in the response body. This object has the following fields.
| Field | Data Type | Description |
|---|---|---|
| httpStatus | Integer | The HTTP status code of the response |
| artStatus | String | An indication of the status of the action. OK means that the operation was successful, ERROR indicates a server or HTTP error, and other values indicate that the operation was not done due to some kind of problem. |
| message | String | A descriptive message e.g. indicating the problem with a request |
| data | Object | Data relevant for the response |
HTTP Statuses
The following HTTP statuses are used.
| Status | Description |
|---|---|
| 200 | The operation was successful |
| 201 | An add operation was successful. The Location header will contain the url of the newly created resource. |
| 400 | There was an invalid value in the request |
| 401 | No authorization details were provided or authorization could not be granted given the credentials presented |
| 409 | A delete could not be performed because related records exist or a new record could not be added because a similar record already exists |
| 500 | An error occurred while performing the request |
ART Statuses
The artStatus field of the ApiResponse can have a number of values as below.
| Status | Description |
|---|---|
| OK | The operation was successful |
| ERROR | There was a server or HTTP error |
| AUTHORIZATION_REQUIRED | There was no Authorization header in the request. Calls to the /api/login endpoint don't require an Authorization header. All other endpoints require this header. |
| UNAUTHORIZED | The operation could not be performed because authorization is not available. This may mean that the user whose credentials have been supplied does not exist, is disabled or doesn't have the use_api permission. It may also mean that token based authentication is not configured i.e. the jwtSecret field in the WEB-INF\art-custom-settings.json file has not been set. |
| RECORD_NOT_FOUND | The referenced record doesn't exist e.g. if trying to retrieve a user's details using the /api/users/{id} endpoint. |
| LINKED_RECORDS_EXIST | Indicates that a delete operation could not be performed because some related records exist e.g. you can't delete a user if that user is the owner of some jobs. |
| RECORD_EXISTS | Indicates that an add operation could not be performed because a similar record already exists e.g. if trying to add a user but another user with the same username already exists. |
| INVALID_VALUE | Indicates that some value provided in the request body is not appropriate e.g. trying to add a user with an empty username. |
Authentication
All calls to the api must contain authentication information. This is contained in the Authorization HTTP header. API authentication always uses the Internal authentication method even though ART may be configured to use other authentication methods.
Basic Authentication
One can use the HTTP Basic authentication method to provide authentication credentials where the Authorization header contains the username and password encoded in base 64 format i.e. Authorization: Basic <base 64 credentials>
Bearer Authentication
One can also obtain a token from the application and supply that with subsequent api calls. The jwtSecret in the WEB-INF\art-custom-settings.json file must have been set to a non-blank string. To obtain a token, perform a POST to the /api/login endpoint providing username and password form parameters. If authenticated, you will receive a response that contains an access token. This token should then be provided in the Authorization header using the Bearer scheme i.e. Authorization: Bearer <token>. By default, tokens expire after 60 minutes. This can be changed from the Settings page using the JWT Token Expiry (Mins) field.
Login
Request
If using bearer authentication, you obtain an access token by performing the following request, passing username and password form parameters
POST /api/login
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"accessToken": "<token>"
}
}
In case the jwtSecret is not set, or the user provided doesn't exist or is disabled or doesn't have the use_api permission, a 401 response like the following would be returned
{
"httpStatus": 401,
"artStatus": "UNAUTHORIZED",
"message": null,
"data": null
}
Users
Getting all users
Request
GET /api/users
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": [
{
"userId": 24,
<other fields>
}
]
}
Getting a particular user
Request
Get by user id
GET /api/users/{id}
Get by username
GET /api/users/username/{username}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"userId": 1,
<other fields>
}
}
In case the user doesn't exist, a 404 response like the following would be returned
{
"httpStatus": 404,
"artStatus": "RECORD_NOT_FOUND",
"message": null,
"data": null
}
Deleting a user
Request
DELETE /api/users/{id}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
In case related records exist, a 409 response like the following would be returned. The data attribute would contain a list of strings which represent the jobs that the user owns.
{
"httpStatus": 409,
"artStatus": "LINKED_RECORDS_EXIST",
"message": "User not deleted because linked jobs exist",
"data": [
"A report (5)",
"Pie (8)",
]
}
Adding a user
Request
POST /api/users
{
"username": "test",
<other fields>
}
The request body should contain a user object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the User object, you can look at the WEB-INF\classes\art\user\User.java file. If using a clear text password, include the clearTextPassword field and set it to true.
Response
If successful, a 201 response like the following would be returned. The Location header in the response will contain the url for the newly created user. The created user is included in the response.
{
"httpStatus": 201,
"artStatus": "OK",
"message": null,
"data": {
"userId": 41,
<other fields>
}
}
If the username is not provided or is blank, a 400 response like the following would be returned
{
"httpStatus": 400,
"artStatus": "INVALID_VALUE",
"message": "username field not provided or blank",
"data": null
}
If a user with the supplied username already exists, a 409 response like the following would be returned
{
"httpStatus": 409,
"artStatus": "RECORD_EXISTS",
"message": "A user with the given username already exists",
"data": null
}
Updating a user
Request
PUT /api/users/{id}
{
"username": "test",
<other fields>
}
The request body should contain a user object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the User object, you can look at the WEB-INF\classes\art\user\User.java file. If using a clear text password, include the clearTextPassword field and set it to true.
Response
If successful, a 200 response like the following would be returned. The updated user is included in the response.
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"userId": 12,
<other fields>
}
}
Disabling a user
Request
POST /api/users/{id}/disable
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
Enabling a user
Request
POST /api/users/{id}/enable
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
Reports
Getting all reports
Request
GET /api/reports
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": [
{
"reportId": 15,
<other fields>
}
]
}
Getting a particular report
Request
Get by id
GET /api/reports/{id}
Get by name
GET /api/reports/name/{name}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"reportId": 1,
<other fields>
}
}
In case the report doesn't exist, a 404 response like the following would be returned
{
"httpStatus": 404,
"artStatus": "RECORD_NOT_FOUND",
"message": null,
"data": null
}
Deleting a report
Request
DELETE /api/reports/{id}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
In case related records exist, a 409 response like the following would be returned. The data attribute would contain a list of strings which represent the jobs that use the report.
{
"httpStatus": 409,
"artStatus": "LINKED_RECORDS_EXIST",
"message": "Report not deleted because linked jobs exist",
"data": [
"A report (5)",
"Pie (8)",
]
}
Adding a report
Request
POST /api/reports
{
"name": "test",
<other fields>
}
The request body should contain a report object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the Report object, you can look at the WEB-INF\classes\art\report\Report.java file.
Response
If successful, a 201 response like the following would be returned. The Location header in the response will contain the url for the newly created report. The created report is included in the response.
{
"httpStatus": 201,
"artStatus": "OK",
"message": null,
"data": {
"reportId": 41,
<other fields>
}
}
If the name is not provided or is blank, a 400 response like the following would be returned
{
"httpStatus": 400,
"artStatus": "INVALID_VALUE",
"message": "name field not provided or blank",
"data": null
}
If a report with the supplied name already exists, a 409 response like the following would be returned
{
"httpStatus": 409,
"artStatus": "RECORD_EXISTS",
"message": "A report with the given name already exists",
"data": null
}
Updating a report
Request
PUT /api/reports/{id}
{
"name": "test",
<other fields>
}
The request body should contain a report object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the Report object, you can look at the WEB-INF\classes\art\report\Report.java file.
Response
If successful, a 200 response like the following would be returned. The updated report is included in the response.
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"reportId": 12,
<other fields>
}
}
Disabling a report
Request
POST /api/reports/{id}/disable
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
Enabling a report
Request
POST /api/reports/{id}/enable
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
Running a report
Request
POST /api/reports/run
As part of the request, form parameters need to be included to provide parameters to be used to run the report, similar to running a report via url in the browser. The reportId parameter is mandatory in order to specify which report to run e.g. .../api/reports/run?reportId=1. Html report formats are not supported when running a report via api.
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"fileName": "report1-2019_06_20-10_50_52_700-WP985-1-0.pdf",
"url": "http://localhost:8080/art/export/reports/report1-2019_06_20-10_50_52_700-WP985-1-0.pdf",
"rowsRetrieved": 12,
"rowsUpdated": null
}
}
If the report is not found, a 404 response like the following would be returned
{
"httpStatus": 404,
"artStatus": "RECORD_NOT_FOUND",
"message": null,
"data": null
}
If a html report format is specified, a 400 response like the following would be returned
{
"httpStatus": 400,
"artStatus": "INVALID_VALUE",
"message": "report format not allowed: html",
"data": null
}
User Groups
Getting all user groups
Request
GET /api/user-groups
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": [
{
"userGroupId": 4,
<other fields>
}
]
}
Getting a particular user group
Request
Get by id
GET /api/user-groups/{id}
Get by name
GET /api/user-groups/name/{name}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"userGroupId": 1,
<other fields>
}
}
In case the user group doesn't exist, a 404 response like the following would be returned
{
"httpStatus": 404,
"artStatus": "RECORD_NOT_FOUND",
"message": null,
"data": null
}
Deleting a user group
Request
DELETE /api/user-groups/{id}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
In case related records exist, a 409 response like the following would be returned. The data attribute would contain a list of strings which represent the users that the user group contains.
{
"httpStatus": 409,
"artStatus": "LINKED_RECORDS_EXIST",
"message": "User Group not deleted because linked users exist",
"data": [
"user1",
"test",
]
}
Adding a user group
Request
POST /api/user-groups
{
"name": "test",
<other fields>
}
The request body should contain a user group object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the UserGroup object, you can look at the WEB-INF\classes\art\usergroup\UserGroup.java file.
Response
If successful, a 201 response like the following would be returned. The Location header in the response will contain the url for the newly created user group. The created user group is included in the response.
{
"httpStatus": 201,
"artStatus": "OK",
"message": null,
"data": {
"userGroupId": 5,
<other fields>
}
}
If the name is not provided or is blank, a 400 response like the following would be returned
{
"httpStatus": 400,
"artStatus": "INVALID_VALUE",
"message": "name field not provided or blank",
"data": null
}
If a user group with the supplied name already exists, a 409 response like the following would be returned
{
"httpStatus": 409,
"artStatus": "RECORD_EXISTS",
"message": "A user group with the given name already exists",
"data": null
}
Updating a user group
Request
PUT /api/user-groups/{id}
{
"name": "test",
<other fields>
}
The request body should contain a user group object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the UserGroup object, you can look at the WEB-INF\classes\art\usergroup\UserGroup.java file.
Response
If successful, a 200 response like the following would be returned. The updated user group is included in the response.
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"userGroupId": 10,
<other fields>
}
}
Jobs
Getting all jobs
Request
GET /api/jobs
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": [
{
"jobId": 8,
<other fields>
}
]
}
Getting a particular job
Request
GET /api/jobs/{id}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"jobId": 1,
<other fields>
}
}
In case the job doesn't exist, a 404 response like the following would be returned
{
"httpStatus": 404,
"artStatus": "RECORD_NOT_FOUND",
"message": null,
"data": null
}
Deleting a job
Request
DELETE /api/jobs/{id}
Response
If successful, a 200 response like the following would be returned
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": null
}
Adding a job
Request
POST /api/jobs
{
"name": "test",
<other fields>
}
The request body should contain a job object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the Job object, you can look at the WEB-INF\classes\art\job\Job.java file.
Response
If successful, a 201 response like the following would be returned. The Location header in the response will contain the url for the newly created job. The created job is included in the response.
{
"httpStatus": 201,
"artStatus": "OK",
"message": null,
"data": {
"jobId": 7,
<other fields>
}
}
If the name is not provided or is blank, a 400 response like the following would be returned
{
"httpStatus": 400,
"artStatus": "INVALID_VALUE",
"message": "name field not provided or blank",
"data": null
}
If a job with the supplied name already exists, a 409 response like the following would be returned
{
"httpStatus": 409,
"artStatus": "RECORD_EXISTS",
"message": "A job with the given name already exists",
"data": null
}
Updating a job
Request
PUT /api/jobs/{id}
{
"name": "test",
<other fields>
}
The request body should contain a job object. You can use JSON format and set the Content-Type header to application/json. For the applicable field names of the Job object, you can look at the WEB-INF\classes\art\job\Job.java file.
Response
If successful, a 200 response like the following would be returned. The updated job is included in the response.
{
"httpStatus": 200,
"artStatus": "OK",
"message": null,
"data": {
"jobId": 6,
<other fields>
}
}
