API Reference

We made a REST server that exposes a set of APIs for managing users and files. The following list contains all the APIs that our server exposes to the client.

api/user/login

• description:

used to login the user. This will check if the given email and associated password exist.

• method: GET
• params to send:
  • email (string)
  • password (string)
• response:
  • Success: JSON with user information
  • Errors: User not found / Invalid password

Usage example:

api/user/signin

• description:

used to register a new user. An error will be returned if the given email already exists, otherwise it will be created a new user inside our remote database.

• method: POST
• params to send (as application/JSON):
  • name (string)
  • surname (string)
  • email (string)
  • password (string)
• response:
  • Success: JSON with user registration information
  • Errors: no JSON is returned (email already in use)

Usage example:

api/user/pswRecovery

• description:

used to start the recovery password process. A password recovery email with a specific link is sent to the email provided by the user if this email is already present in the database, then a registration exists. This link will contain the "uuid" and "pgid" params information that will be used then by the API /changePassword called in the next dedicated page. When a password recovery procedure starts, for that request a ChangePassword schema is created inside the remote database, and these information are stored here.

• method: POST
• params to send (as application/JSON):
  • email (string)
• response:
  • Success: "true" (if the email has been successfully sent)
  • Errors: "Email not found" (if the email does not exist in the database)

Usage example:

api/user/changePassword

• description:

used to update the password of an user with a new password. This is the second step of the password recovery API. "uuid" and "pgid" must be passed, and their values come from the result of pswRecovery API; the value of "password" is inserted by the user in the dedicated client page.

• method: GET
• params to send:
  • uuid (string)
  • pgid (string)
  • password (string)
• response:
  • Success: JSON with updated user information
  • Errors: "PasswordChange not found" (if uuid and pgid values are not correct)

Usage example:

api/user/getUser

• description:

 used to retrieve an user simply passing an user id.

• method: GET
• params to send:
  • id (string)
• response:
  • Success: JSON with user information
  • Errors: JSON with "Internal server error" (if the given id does not exist)

Usage example:

api/file/createRepository

• description:

used to create a public or private repository for the given user. The params needed are "userId", "publicR" (true for creating a public repository; false instead for a private repository), "repositoryName" that is the name of the repository that will be shown to the users and "autore" that contains the real name of the repository creator. Notice that the file system that we implemented, stores all folders and file locally on our server, inside the dedicated folder "BPMFiles": using this API if the user does not have already a folder for him inside the "BPMFiles" folder, this folder, named with the user id, will be created, then the folder for the new repository will be created too, named with an unique id.

 Please see File System page on this Wiki for more information about our file system.

• method: GET
• params to send:
  • idUser (string)
  • publicR (boolean)
  • repositoryName (string)
  • autore (string)
• response:
  • Success: JSON with repository path information
  • Errors: JSON with "Internal server error" (if the given user id does not exist)

 

Usage example:

api/file/createFolder

• description:

this API is used to create a folder inside a repository. The params needed are "idUser" that is the id of the current user, "idRepository" that is the id of the repository where the folder will be created, "folderName" that is the real name of the folder that will be shown to the user and "autore" that is the name of the user that is creating the folder.

• method: GET
• params to send:
  • idUser (string)
  • idRepository (string)
  • folderName (string)
  • autore (string)
• response:
  • Success: JSON with folder information
  • Errors: JSON with "Internal server error" (if the given user id, or repository, id do not exist)

Usage example:

api/file/createFile

• Description:

 this API is used to create a new file inside a repository or a folder. The params needed are "idUser" that is the id of the current user, "idRepository", "idFolder" (optional) that specifies the id of a folder where the user is creating the file (if that folder exist inside the repository), "originalName" that is the name of the file that will be shown to the users, "autore" that is the name of the user that is creating the file and "fileType" that assumes two value, "coreography" or "collaboration". This API will create a folder that is "hidden" to the user, but is used by the file system to wrap all the different versions of a single bpmn file. This API creates the file version n°1. The actual name of the file, ie the one not shown to the user but used in the file system, consists of the concatenation created by a dot between the id of this hidden wrapping folder and the file version.

• method: GET
• params to send:
  • idUser (string)
  • idRepository (string)
  • idFolder (string)
  • originalName (string)
  • autore (string)
  • fileType (string)

 

• response:
  • Success: JSON with the information of the new file
  • Errors: JSON with "Internal server error" (if the given user id, repository id or file type do not exist, or the given folder id is wrong)

Usage example:

api/file/uploadFile

• Description:

This API is used to upload a file from the user's local machine. The file thus loaded can be placed directly at the repository level or inside a folder; a new schema containing all the information it is saved in the database and the current version is 1. The request type is MULTIPART_FORM_DATA so the params are "idUser", "idRepository", "autore", "fileType" and the uploaded file "files" itself.

• method: POST
• params to send:
  • idUser (string)
  • idRepository (string)
  • autore (string)
  • fileType (string)
  • files (file)
• response:
  • Success: the file is updated
  • Errors: JSON with "Internal Server Error" message

 

api/file/modifyBodyFile

• Description:

 This API is used to upload a specific version of a file from the user's local machine. The file version thus loaded need to be placed directly inside the hidden wrapping folder for that file, and is going to replace that file with the specified version; this folder can be at repository level or inside a folder. The request type is MULTIPART_FORM_DATA so the params are "idUser", "idRepository", "idFolder" (optional), "version" and the uploaded file "files" itself.

• method: POST
• params to send:
  • idUser (string)
  • idRepository (string)
  • idFolder (string)
  • version (string)
  • files (file)
• response:
  • Success: "OK"
  • Errors: JSON with "Internal Server Error" message

api/file/downloadFile

• Description:

 this API allows the user to download a specific file on his local machine. The params needed are "idFile" that is the id of the file that the user wants to download and the "version".

• method: GET
• params to send:
  • idFile (string)
  • version (string)
• response:
  • Success: the download for the indicated file starts
  • Errors: the download for the indicated file doesn't start (if the given file id does not exist in the database)

Usage example:

api/file/getAllRepo

• Description:

this API returns a list of repository for a specific user. The param needed is "idUser".

• method: GET
• params to send:
  • idUser (string)
• response:
  • Success: JSON with all the repositories information
  • Errors: empty JSON (if the given id does not exist in the database)

Usage example:

 

api/file/getRepoSpec

• Description:

 this API returns information about a specific repository. The param needed is "id" of the desired repository.

• method: GET
• params to send:
  • id (string)
• response:
  • Success: JSON with the repository information
  • Errors: empty JSON (if the given id does not exist in the database)

Usage example:

api/file/getAllFile

• Description: this API returns a JSON with a list of file inside a repository or a folder. The params needed are "idRepository" and "idFolder" (optional).
• method: GET
• params to send:
  • idRepository (string)
  • idFolder (string)
• response:
  • Success: JSON with information for all file inside a repository or a folder
  • Errors: empty JSON (if the given ids don't exist in the database)

Usage example:

api/file/getAllFolders

• Description:

 this API returns a JSON with a list of folders inside a repository. The param needed is "idRepository".

• method: GET
• params to send:
  • idRepository (string)
• response:
  • Success: JSON with information for all the folders inside the repository
  • Errors: empty JSON (if the given id does not exist in the database)

Usage example:

api/file/getFolderSpec

• Description:

 this API returns a JSON with information about a specific folder, indicated by the param "id" for the folder.

• method: GET
• params to send:
  • id (string)
• response:
  • Success: JSON with information for the specific folder
  • Errors: empty JSON (if the given id does not exist in the database)

Usage example:

api/file/createNewVersion

• Description:

this API is used for the creation of a new version for an existing file. The params needed are "idFile" and the "version". The needed "version" is the current version of the file that the user wants to upgrade: server will create a new version for the indicated file, copying the file with the version indicated and renaming it at the end with the new highest version available for that file. For example, if the user, taken a file that has 5 versions wants to create a new version starting from its version 1, will indicate "version" = 1 and the server will create a copy in the file system for that version 1 file renamed at the end with the value 6 (which indicates that version number 6 was created). That new file will be placed inside the hidden wrapping folder containing all the file versions.

• method: GET
• params to send:
  • idFile (string)
  • version (string)
• response:
  • Success: JSON with information for the new version of the file
  • Errors: empty JSON (if the given file id does not exist in the database) / "Version does not exist" (if the given version that the user wants to copy does not exist)

Usage example:

api/file/modifyRepoName

• Description:

 this API is used to change the name of a specific repository, ie the one that is shown to the user and not the one in the file system. The required params are "idRepository" and "newRepoName".

• method: GET
• params to send:
  • idRepository (string)
  • newRepoName (string)
• response:
  • Success: JSON with updated information for the repository
  • Errors: "Repository not found" (if the given idRepository does not exist in the database)

Usage example:

api/file/modifyFileName

• Description:

 this API is used to change the name of a specific file, ie the one that is shown to the user and not the one in the file system. The required params are "idFile" and "newFileName".

• method: GET
• params to send:
  • idFile (string)
  • newFileName (string)
• response:
  • Success: JSON with updated information for the file
  • Errors: "File not found" (if the given idFile does not exist in the database)

Usage example:

api/file/modifyRepoVisibility

• Description:

this API is used to change the visibility for a repository. The params needed are "idRepository" and "newRepoVisibility" that can assume value true (to set the repository to public) or false (to set the repository to private).

• method: GET
• params to send:
  • idRepository (string)
  • newRepoVisibility (boolean)
• response:
  • Success: JSON with updated information for the repository
  • Errors: "Repository not found" (if the given idRepository does not exist in the database)

Usage example:

forum di facebook

api/file/modifyFolderName

• Description:

this API is used to change the name for a folder, ie the one that is shown to the user and not the one in the file system. The required params are "idFolder" and "newFolderName".

• method: GET
• params to send:
  • idFolder (string)
  • newFolderName (string)
• response:
  • Success: JSON with updated information for the folder
  • Errors: "Folder not found" (if the given idFolder does not exist in the database)

Usage example:

api/file/getFileSpec

• Description:

 this API is used to retrive information for a specific file. The required param is the file "id".

• method: GET
• params to send:
  • id (string)
• response:
  • Success: JSON with file information
  • Errors: "File not found" (if the given idFile does not exist in the database)

Usage example:

api/file/getAllRepoPublic

• Description: this API is used to retrive information for all the public repository in the database. No params are needed.
• method: GET
• params to send: none
• response:
  • Success: JSON with all public repositories information
  • Errors: none

Usage example:

api/file/deleteVersion

• Description:

 this API is used to delete a specific version for a file. Params needed are "idFile" and "version": the file with the indicated version and id is deleted from the file system, moreover on the file entity inside the db a deletedVersion array keeps track of every version number of the deleted file versions.

• method: GET
• params to send:
  • idFile (string)
  • version (string)
• response:
  • Success: "true"
  • Errors: none

Usage example:

api/file/exportCollection

• Description:

this API is used to export the collection of all versions for a specific file in zip format. When the "idFile" is received, all the files on the corresponding hidden wrapping folder are zipped into an archive, named with the original file name (different from the one used by the file system).

• method: GET
• params to send:
  • idFile (string)
• response:
  • Success: download of the zipped collection of file versions will start
  • Errors: JSON with "internal error" message if the idFile does not exist inside the db

Usage example:

api/file/moveFile

• Description:

 this API is used to move a specific file from a specific location to another location of the same repository. The params needed "idUser", "idRepository", "idFolder" (optional) are related to the destination where the user want to move the file; instead "idFile" and "paths" are params that are related to the id of the file that the user is moving and the path where the moving file is located, respectively.

• method: GET
• params to send:
  • idUser (string)
  • idRepository (string)
  • idFolder (string)
  • idFile (string)
  • paths (string)
• response:
  • Success: the file is correcly moved
  • Errors: the wrong path, if almost one of the id passed is not correct

Usage example:

api/file/deleteFile

• Description:

this API is used to delete a file. Removing a file means remove entirely the hidden wrap folder and all the file inside this folder (the different versions of the file). Params needed are "idFile" that is the actual name of the hidden folder, "idRepository", "idUser" and "idFolder" that is optional (use only if the file is inside a folder).

• method: GET
• params to send:
  • idRepository (string)
  • idUser (string)
  • idFolder (string)
  • idFile (string)
• response:
  • Success: the file (so the hidden wrapping file versions folder) is correcly deleted
  • Errors: JSON with "Internal Server Error" if one of the given ids does not exist

Usage example:

api/file/addValidity

• Description:

given an "idFile", this API is going to update information about "soundness", "safeness" and "validity" for that file.

• method: GET
• params to send:
  • idFile (string)
  • soundness (string)
  • safeness (string)
  • validity (boolean)
• response:
  • Success: JSON with updated file information
  • Errors: JSON with "Internal Server Error" if the given id does not exist

Usage example:

api/share/repository

• Description:

this API is used to share a repository. The visibility of the specified repository will be set to public, while an email is sent to the email of the user which we want to share the repository to, and contains the link that points to this shared repository. Params needed are the "idRepository" and the "emailTo".

• method: GET
• params to send:
  • idRepository (string)
  • emailTo (string)
• response:
  • Success: "true" (the email is sent to the user)
  • Errors: "Repository not found" (if the idRepository does not exist in the database) / JSON "Internal Server Error" (if the email could not be sent)

Usage example:

api/share/file

• Description:

 this API is used to share a file. For doing that, a new public repository is created, the file (so the hidden folder with all the versions of that file) is copied into that new repository, while an email is sent to the email of the user which we want to share the file to, and contains the link that points to this shared repository with the copy of the specified file. The params needed are "idFile" (file to share), "emailTo", "repositoryName" (the name of the new repository that will be created), "idUser" (id of the user folder where we want to create the new repository) and "autore" (of the new repository).

• method: GET
• params to send:
  • idFile (string)
  • emailTo (string)
  • idUser(string)
  • repositoryName (string)
  • autore (string)
• response:
  • Success: "true" (the email is sent to the user)
  • Errors: "File not found" (if the idFile does not exist in the database) / JSON "Internal Server Error" (if the email could not be sent)

Usage example:

/api/modelcheck/upload

• Description:

Run a DFS algorithm on the models to generate the related LTS contained in the .aut files.

• method: POST
• params to send:
  • collaboration (File)
  • choreography (File)
• response:

The result is a JSON File if the response is success. In the Json file there are two fields:

• choreography (that contain the choreography’s name of the .aut file)
• collaboration (that contain the collaboration’s name of the .aut file)

Return 500 Internal Error, if an error occurs.

 

 

 

 

 

/api/modelcheck/download

 

• Description:

Download the .aut file whose name is specified as a parameter in the "filename" and a boolean to specify if is a collaboration or a choreography model..

• method: GET
• params to send:
  • filename ( contain the String of name of the .aut file)
  • collaboration ( is a boolean, true if is a collaboration file, false if is a choreography file)
• response:

Download the file in your system

 

/api/modelcheck/check_equivalence

• Description:

Use the "ltscompare" executable of the MCRL2 tool to perform the equivalences Trace, Branching and Bisimulation between models, with or without Weak.

• method: POST
• params to send:
  • weak (boolean, true o false)
  • equivalence ( contain “Trace”, “Branching” or “Bisimulation” value)
  • collaborationPath (name of .aut collaboration file)
  • choreographyPath (name of .aut choreography file)
• response:

Return a Json object that contain the following fields: “state”,”resultState”,”command”,”log”,”result”,”counterExample”

 

/api/modelcheck/mergemodel

• Description:

It takes 2 collaboration files as input generates a file that corresponds to the merge of the two files, if they meet certain requirements.

Connect a task sender of one file with the task receiver of the other file via message flow only if the message flows have the same label on both files.

• method: POST
• params to send:
  • sender (sender collaboration file)
  • receiver (receiver collaboration file)
• response:

- File containing both models linked via messageFlow

- If the models have a different number of message flows -> returns BadRequest 400 with a message

- A name of a message flow of the first model is not present in the second model -> returns BadRequest 400 with a message

- A name of a message flow of the second model is not present in the first model -> returns BadRequest 400 with a message

- The name is present but the message flow sender of one model does not have the respective receiver in the other model (and vice versa) -> returns BadRequest 400 with a message