User & Account API

The User and Account API handles all authentication/authorisation, account management, and file operation functions for the ENSIMS Web Service. The authentication mechanism uses JSON Web Tokens (JWT) stored and transmitted in cookies. Please note that the ENSIMS Web Service is not designed for storage of important/sensitive data. If your project requires enhanced security, please contact us before uploading data to the service.

Methods Summary

The User and Account API includes the following functions:

Authentication/Authorization: Log on, Log off, check-in (with the existing token), confirm (check user credential against token)
Account management: Register, retrieve account information, update account information
File operations: List upload folder, upload file(s), download files, delete files
Notifications: send email notifications

API

The API methods are summarized in the table below. The base URL of the Users API is:

https://api.ensims.com/users/api

Group	Command	OP	Base	URL	Token	Payload	Return
General	Version info inquiry	GET	*	/info	none	none	Show version info
Auth	Log on	POST	*	/logon	none	User credential	Auth return
	Check in	POST	*	/checkin	JWT	none	Auth return
	Log off	POST	*	/logout	JWT	none	Auth return
	Confirm credential	POST	*	/confirm	JWT	User credential	Auth return
Account	Get account info	GET	*	/user	JWT	none	Account details
Account	Update account info	POST	*	/user	JWT	Account details	Transaction Response
Files	Get directory	GET	*	/files/<path to a folder>	JWT	none	Folder contents
	Upload files to root	POST	*	/files	JWT	MultiPart	File handle
	Upload files to folder	POST	*	/files/<folder/path>	JWT	MultiPart	File handle
	Download files	GET	*	/files/<path to a file>	JWT	none	File contents
	Delete files	DELETE	*	/files/<path to a file/folder>	JWT	none	Transaction Response
Other	Send email	POST	*	/send	JWT	Mail body	Transaction Response

Access the API

The REST API is accessible with any HTTPS client that allows you to assign data to the header and the body of each request, and send/receive cookies. The ENSIMS Web Service uses mainly the GET, the POST and the DELETE methods. To experiment and test the API commands, we recommend Postman.

Depending on the programming language you are using, there are numerous HTTPS client to choose from. In this document, the examples of using curl and Requests for Python are provided in the descriptions of each transaction. Here is a quick example using the get version info command.

Browser

Since the info command does not require authentication, you can try it in a web browser by typing in the following URL:

https://api.ensims.com/users/api/info

If the service is accessible, you will receive a page containing the following text:

{
  "Title" : "Users Web API",
  "Description" : "JESS User Management API provided by ENSIMS Ltd.",
  "Major" : 1,
  "Minor" : 0,
  "Revision" : 0,
  "Release" : "beta",
  "Update" : 0,
  "Notice" : "(C) 2017, Energy Simulation Solutions Ltd. All rights reserved."
}

curl

Send the same command using curl:

curl https://api.ensims.com/users/api/info

The same text will be return with successful execution.

Requests

Make sure Requests is correctly installed in your Python environment, and run the following the lines:

>>> import requests
>>> r = requests.get('https://api.ensims.com/users/api/info')
>>> r.json

Table of Contents