e-satisfaction
Updated :
Getting Started
e-satisfaction has a service API which is available to all the users of the platform to perform a set of pre-defined actions.
Read below on this document how to read our API specification and how to interact with it.
This guide is suitable for getting started with e-satisfaction API so that it can be used in cases like manual questionnaire distribution or data retrieval.
RESTful API
e-satisfaction API is designed taking into consideration the REST principles and is trying to get as closer as possible to the specifications.
Request Methods
The API makes use of all http methods that the REST specification defines based on the operation each time.For that reason, this document makes use of the following methods:
POST, PATCH, GET, DELETE
Payload Structure
The payload of each request can be provided using two formats:
- key-value pairs, either in the url (for GET requests) or on the request body (for POST, PATCH or DELETE methods)
- json, on the request body, for all http methods
In the context of this document, and for easier understanding of the parameters, we are going to use the json format, and this is the one we suggest for implementing API calls.
Responses
All API responses include full entities, based on the operation, according to the REST specification.
Response Fields
On each API call, you can use an extra argument called response_fields and define all the response fields that you need the API to return. No value for this parameter means that it will return all the fields of the requested resource.
You can send response_fields as an array of values, the fields you wish the API to return.
HTTP Status Codes
Based on the status of each operation, a response might have one of the following HTTP Status Codes:Normal operation codesOn a successful operation, one of the following status codes will be returned, based on the operation.
| Code | Description | Reason |
| 200 | OK | Successful Operation |
| 201 | Created | Object/Entity created with success |
| 204 | No Content | Successful Operation. No content provided. Usually in DELETE operations |
On an error, one of the following status codes will be returned, based on the error.
The following codes will be documented on each request explicitily.
| Code | Description | Reason |
| 400 | Bad Request | In cases where the input is invalid |
| 404 | Not Found | If the referenced entity/object does not exist |
| 409 | Conflict | If the operation performed is in conflict with another operation or with the object state |
Error codes
The following error codes can be thrown on any request and thus there is no need to document them explicitily.
Error codes can be thrown almost on any request and they documented only to define an expected behavior.
| Code | Description | Reason |
| 401 | Unauthorized | If the provided jwt is not valid |
| 403 | Forbidden | If no jwt is provided |
| 500 | Internal Server Error | An unexpected error occurred. We are getting notifications about these errors and we should fix it ASAP |
| 501 | Not implemented | In cases where the requested operation is not implemented on the entity/object |
Versions - Compatibility
e-satisfaction API is structured in versions. Current version is v3.2.
Versions follow the Semantic Versioning specification, which means that all minor and lower releases will have no breaking changes.
To highlight the specification, given a version number MAJOR.MINOR.PATCH, we increment the:
- MAJOR version when we make incompatible API changes,
- MINOR version when we add functionality in a backwards-compatible manner, and
- PATCH version when we make backwards-compatible bug fixes.
In our API, we are followig the MAJOR.MINOR format for our versions, where:
- MAJOR versions are for backward incompatible changes (e.g. brand new API)
- MINOR versions are for whole new features
All bug fixes and small improvements will be integrated silently into the latest version (starting from the one affected, if bug, and merge up).
Compression
All API responses are compressed using gzip and a response header Content-Encoding: gzip is returned always.
Although all major libraries can handle properly the above compression, keep in mind to uncompress if you are using your own custom library.
Feedback
We are always trying to keep our documentation up-to-date with all the latest changes. However, if you find any issues that might affect your implementation and this documentation should be updated, please let us know by sending a request at support@e-satisfaction.com.
In case of security vulnerabilities, please add a subject line with a prefix of [e-satisfaction API Security Vulnerability] and we will address it immediately.
Documentation
All API requests are being documented separately on the Apiary platform and you can take a look at our own documentation here: https://esatisfactionv3.docs.apiary.io
Authentication
Before starting using the API, you should read about our API Authentication in order to set yourself up properly.
How to test the API
Before getting your code to production, you can test our API freely without the need of a sandbox account. Read more about API Testing.