meta data for this page

User & Account API

Version 1.0, ©2020 Energy Simulation Solutions Ltd


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
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