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