opensupports/server/API_STANDARD.md

OpenSupports can work completely fine without a frontend. You could only use this API to manage the system. This documentation is intended for application developers who are looking to integrate OpenSupports with other applications.

Request/Response Interface

The API server is located in the api/ folder of your OpenSupports' instance folder. All the requests must be done via POST method, with the exception of the path /system/download.

The response object has the following JSON structure:

{
  status: ["success"/"fail"],
  message: [String],
  data: [Object/Array/String]
}

• status indicates "success" if the request succeeded, else contains "fail"
• message contains the message in case of failure.
• data contains the returned data of the request.

For each path, we will document first the Parameters, then the success content of the property data, and finally the possible error messages it can return.

Session Permissions

Some paths will not work if you're not logged in. All paths have documented a "Permission" that can be:

• any: anyone can do a request, even if it's not logged in.
• user: only logged regular users can do the request.
• staff1: only a logged staff member with at least level 1 can do the request.
• staff2: only a logged staff member with at least level 2 can do the request.
• staff3: only a logged staff member with at least level 3 can do the request.

To login, user or staff, you have to make a request to /user/login This request will return you the session data with an userId and a token. You will use these to validate the session every time you make a request that requires a logged user.

All the paths that have permission user, staff1, staff2 or staff3, require userId and token to be passed as parameter. You need to pass them as csrf_userid and csrf_token respectively.

If you don't pass the userId and token, a NO_PERMISSION error will be returned.

Additionally, if there are no users (only staff members), you can check a ticket you created by providing your email and the ticketNumber to the /ticket/check path. This path will return you a token and ticketNumber you will use to comment, retrieve, or do any other operations to the ticket.

File Attachments

We have two settings for file attachment:

• allow-attachments setting flag indicates if users can attach files.
• max-size setting indicates what is the file size limit in MB.

When you want to attach images to a ticket, comment or article; you can place the string IMAGE_PATH_i inside the parameter content. IMAGE_PATH_i indicates that it should be replaced with the path of the image of index i (zero-indexed).

You may also include the images parameter indicating the number of images; and image_i parameters, which contain the image file object of index i.

For example

/article/add
title = 'article title'
content = 'this is an article <img src="IMAGE_PATH_0"/> with two images <img src="IMAGE_PATH_1"/>'
position = 1
topicId = 1
images = 2
image_0 = <File>
image_1 = <File>

This request will upload image_0 and image_1. After that, it will replace IMAGE_PATH_0 and IMAGE_PATH_1 with the corresponding urls for each image. The rest of the request will operate normal.

Please remember that max-size setting applies also to images.