EveryRESTFulAPI
EveryRestFulAPI is a powerful RESTful API plugin and a core component of the EveryDataStore ECM platform. It provides a secure and dynamic interface that connects the backend and frontend, enabling efficient data exchange within a single DataStore.
Security note: Users can only access data within the DataStore they are currently logged into. In multi-DataStore environments (e.g., Client1 and Client2), cross-DataStore access is blocked to maintain strict data isolation and security. More details are available in the “Security” section.
EveryRestFulAPI is offered under different license models. The free Community License restricts usage to 1 DataStore, 5 Users, 20 RecordSets, and 10,000 RecordSetItems, intended for non-commercial use. Commercial use requires a Pro or Enterprise License, which provide increased limits, additional features, and professional support.
For detailed information on licensing and pricing, please visit the License & Pricing page.
1. Types of Information Exchange
The exchange of information between the front- and back-end can happen as follows:
- Metadata of a data RecordSet of a data model is sent from the frontend to the backend via a WebForm.
- A list of data RecordSet of a data model is called up via the backend and listed in the frontend.
- Documents relating to the metadata are uploaded via the backend and retrieved from the frontend.
2. HTTP-Methods
The exchange of information via the EveryRESTFul API is handled using the following methods:
GET |
used to retrieve information of a data model from the backend |
POST |
used to send new information about a data model to the backend |
PUT |
used to change certain information of a data model in the backend |
DELETE |
used to delete certain information of a data model in the backend |
3. Standard URL Scheme
In order to correctly exchange information between the front- and back-end, the URL of the API call must be structured as follows:
https://your-api-url/Model/Method/Slug/?paramame1=...
Authorization
|
Bearer {apitoken} |
Scheme |
https://your-api-url/Model/Method/Slug/?Fields={param1=value1,param2=value2}& Filter={param1=value1,param2=value2}& Page={value}& Length={value}& TotalResults={value}& OrderColumn={value}& OrderOpt={asc or desc}& |
|
Explanation of the API parameters |
your-api-url |
HTTP-URL to the API e.g. https://rest.everydatastore.org |
Model |
The name of the data model to be retrieved, e.g. Group. The following URL example returns all groups of a DataStore: https://rest.everydatastore.org/Group/?paramname1=… |
Method |
Method can be a public function within the data model or a relation. Example: getFormFields is a public function of the class Group. In this case, the scheme is structured as follows: https://rest.everydatastore.com/Group/getFormFields?paramname1=... The example returns the form elements of the data model Group. |
Slug |
A unique string value for a data RecordSet from the database. The data RecordSet can be identified using the Slug. Slug can be integrated into the URL in two ways: 1. The following example returns all information (fields and relations) of a certain group with the Slug abcdef12345: https://rest.everydatastore.org/Group/abcde12345 2. The following example returns all members of a certain group with the slug abcdef12345: https://rest.everydatastore.org/Group/Members/abcde12345 |
apitoken |
Apitoken is a hash value consisting of 100 characters. It is used to log the user into the API. Each apitoken has an expiration date. Each user has his/her own apitoken. The lifetime of a token can be set in the admin panel under settings. |
Fields |
Contains the metadata of a data RecordSet of a data model, e.g. Fields={Title=My Group, Description=My first group creation with the api} Field is used in the API call to create a new or change an existing data RecordSet using POST HTTP METHOD in the backend. |
Filter |
Contains the metadata of a data RecordSet, e.g.: fields = {Created = 01.01.2021}. This URL parameter is used to filter data RecordSets of a data model using GET HTTP-METHOD. Search filters from SilverStripe can also be used here, see: https://docs.silverstripe.org/en/4/developer_guides/model/searchfilters/ |
Page |
Default = 1. Page is used with the GET-METHOD to restrict the database query in the backend. |
Length |
Default = 10. Length is used with the GET-METHOD to restrict the database query in the backend. |
TotalResults |
Default = 10000. TotalResults is used with the GET-METHOD to limit the maximum number of queried data RecordSets in the backend or database. |
OrderColumn |
Default = Created. OrderColumn is used with the GET-METHOD to sort the results of the database query based on a specific column. |
OrderOpt |
Default = ASC. OrderOpt is used with the GET-METHOD to determine the sorting direction (ASC or DESC) of the database query result. |
Version |
Determines the version of a data RecordSet and GET-METHOD is used. |
Rollback |
Used to roll back a RecordSet to a particular old version. |
DeleteType |
Default = logically. DeleteType specifies whether a data RecordSet is to be deleted logically or physically. Used with the DELETE METHOD. |
4. Custom URL Scheme
The interface EveryRESTFulAPI can be extended by an extension in the everyrestfulapi/src/Custom/ directory in order to add special functions to the API:
The custom URL scheme is structured as follows:
https://your-api-url/Custom/ExtensionName/Method/Param/
The following example shows how the API can be extended by an extension:
The API should be available via the following URL:
https://your-api-url/Custom/CustomMe/OutMe/abcde12345/
5. Security
For the secure exchange of information with the API interface, an apitoken must be sent with the request header:.
curl https://your-api-url/Model/Method/Slug/?Fields={...}&.....
-H "Accept: application/json"
-H "Authorization: Bearer {apitoken}"
An apitoken is a hash value consisting of 100 characters and it is used to log the user into the API using the apitoken.
Every apitoken has an expiration date.
Each user receives his/her own apitoken.
The lifetime of a token can be set in the everydatastor/config/everydatastore.yml
EverRESTFulApi provides the following security calls:
5.1 getToken
Returns the apitoken to reset. Fields is an array and contains valid login data (Email + Password).
getToken |
https://your-api-url/auth/gettoken |
Description |
Returns the apitoken and member properties to reset. Fields is an array and contains valid login data (Email + Password). |
Method |
GET |
Data(array) |
“Fields“:[{ “Email“: “rest@everydatastore.org“}, {“Password“: “WeLoveSilverStripe“}] |
Response-Success |
[{"Slug":"...."}, {"Token":"...."}, {"Expire":"...."}, ....] |
Response-Error |
HTTP-Code: 400 Response-Text: The Email does not exist. Please contact the App Administrator |
5.2 resetToken
resetToken |
https://your-api-url/auth/resettoken |
Description |
With the resetToken call, an existing and valid apitoken can be reset and regenerated. |
Method |
GET |
Data(array) |
“Fields“:[{ “Email“: “rest@everydatastore“}, {“Password“: “welove“}] |
Response-Success |
[{"Slug":"...."}, {"Token":"...."}, {"Expire":"...."}, ....] |
Response-Error |
HTTP-Code: 400 Response-Text: The Email does not exist. Please contact the App Administrator |
5.3 logout
resetToken |
https://your-api-url/auth/logout |
Description |
This call destroys the API token |
Method |
GET |
Response-Success |
ok |
Response-Error |
HTTP-Code: 400 Token does not exists |
5.4 validatepassword
validatepassword |
https://your-api-url/auth/validatepassword |
Description |
Before a password is changed, it must be checked according to the following criteria: 1. A password must not have been used in the past 2. Minimum length is 8 characters 3. Maximum length is 30 characters
Fields is an array and contains Email, OldPassword and Password (new) |
Method |
GET |
Data(array) |
“Fields“:[{ “Email“: “rest@everydatastore.org“}, {“OldPassword“: “WeLoveSilverStripe“}, {“Password“: “newwelove“}] |
Response-Success |
200 ok |
Response-Error |
HTTP-Code: 200 Response-Text: The provided details do not seem to be correct. Please try again.
Or HTTP-Code: 400 Response-Text: E-mail, old password, password or API-Token are missing.
Or Response-Text: Password is too short, it must be {minimum} or more characters long. Or Or HTTP-Code: 400 |
5.6 changePassword
changePassword |
https://your-api-url/auth/changePassword |
Description |
With the changePassword call, registered users can change their own password using apitoken and email. Fields is an array and contains Email, OldPassword and Password (new) |
Method |
GET |
Data(array) |
“Fields“:[{ “Email“: “rest@everydatastore.org“}, {“OldPassword“: “WeLoveSilverStripe“}, {“Password“: “NewWeLoveSilverStripe“}] |
Response-Success |
Password has been changed |
Response-Error |
HTTP-Code: 400 Response-Text: Login is failed or fields are missing. |
5.7 getResetPasswordLink
getResetPasswordLink |
https://your-api-url/auth/getResetPasswordLink?Email=reset@everydatastore.com |
Description |
Sends the link to reset the user's password via email. |
Method |
GET |
Data(array) |
Email=reset@everydatastore.com |
Response-Success |
ok |
Response-Error |
HTTP-Code: 400 Response-Text: The Email does not exist. Please contact the App Administrator. |
5.8 checkResetPasswordLink
checkResetPasswordLink |
https://your-api-url/auth/checkResetPasswordLink?Slug=....&Token=... |
Description |
Checks whether the link to reset the user password using the Slug (member slug) and token (autologin token) is valid. If the login is valid, a new apitoken is generated. |
Method |
GET |
Data(array) |
Slug=....// Member Slug |
Response-Success |
[{"Slug":"...."}, {"Token":"...."}, {"Expire":"...."}, ....] |
Response-Error |
HTTP-Code: 400 Response-Text: The password reset link is invalid or expired. |
5.9 resetPassword
resetPassword |
https://your-api-url/auth/resetPassword |
Description |
A new user password can be set with the resetPassword call. Fields is an array and contains member slug and the new password. |
Method |
GET |
Data(array) |
“Fields“:[{ “Slug“: “....“}, {“Password“: “newwelove“}] |
Response-Success |
ok |
Response-Error |
HTTP-Code: 400 Response-Text: The provided login details do not seem to be correct. Please try again.
Or HTTP-Code: 400 Response-Text: Slug, password or API-Token are missing.
Or HTTP-Code: 400 Response-Text: Password is too short, it must be {minimum} or more characters long. Response-Text: Password is too long, it must be {maximum} or less characters long.
Response-Text: You have already used that password in the past, please choose a new password. |
5.10 Configuration
In order to be able to guarantee the security of the information exchange of the EveryRESTFullAPI, various configurations must be defined in the file everyrestfulapi/_config/everyrestfulapi.yml
5.10.1 Global Settings
Configuration |
Description |
Cors: |
Cors settings: |
- Enabled |
True or False. Indicates whether the calls should be checked on Cors |
- Allow-Origin |
Determines from which host the calls can be made |
- Allow-Methods |
Determines which HTTP METHODs are allowed. Default 'GET, POST, OPTIONS' |
- Max-Age |
Determines how long a response header will be cached |
SilverStripe\ORM\DataObject: |
DataObject Settings: |
- API_Allowed_Methods |
Determines which DataObject method can be called via the API |
5.10.2 Data Model Settings
For each data model that is to be retrieved via the EverRESTFullAPI, the following configurations must be defined in everyrestfulapi/_config/everyrestfulapi.yml. This increases the security of the information exchange via the API.
Configuration |
Description |
Data-Model-ClassName: |
A data model can be identified using the class name in the configuration file, e.g. EveryDataStore\Model\DataStore |
- API_View_Fields |
Describes a list of fields or methods of a data model that can be accessed via the API |
- API_Create_Fields |
Describes a list of fields of a data model that may be created via the API |
- API_Edit_Fields |
Describes a list of fields of a data model that can be edited via the API |
- API_Filter_DataStoreID_Map |
Describes the Field DataStoreID of the data model.
Das ein Field direkt aus dem Daten-Model z.B. oder einer Relation z.B. RecordSet. DataStoreID |
- API_Dataobject_Allowed_Relations |
Describes a list of relations of the data model that can be queried via the API. |