EveryRESTFulAPI

EveryRESTFulAPI is the most importan part of "EveryDataStore ECM" package and runs as an independent plugin. It is a RESTFul interface that acts as a bridge between the backend and the frontend to ensure a secure exchange of information. The interface is built dynamically. The information for the frontend is obtained through API calls.

Important note: The API calls can only take place within a DataStore.
For example, if an EveryDataStore project consists of two DataStores (Client1 and Client2) and a User is logged into Client1 via the frontend, he/she can only access information from Client1. Information exchange between several DataStores is blocked by the RESTFulAPI for security reasons. More about this in the section "Security".

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}& Version={value}& DeleteType={logically \|\| }
	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/

1. We create an extension "CustomMe" in the directory:

everyrestfulapi/src/Custom/ and name the file CustomMe.php

2. We initialize the extension CustomME as follows:

namespace EveryRESTfulAPI\Custom;

class CustomMe{

}

3. We create a public static method, e.g. "outME" in the CustomMe class, which we want to retrieve via the API.

namespace EveryRESTfulAPI\Custom;

class CustomMe{

public static outMe($request, $slug= null){

//do some nice things

$ret = slug ? [“Slug“ => slug ] : null;

return $ret ;

}

In the example above, when the URL https://your-api-url/Custom/CustomMe/OutMe/abcde12345/ is called, the API delivers the following response:

[{ "Slug": "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 HTTP-Code: 400 Response-Text: Password is too short, it must be {minimum} or more characters long. Or HTTP-Code: 400 Response-Text: Password is too long, it must be {maximum} or less characters long. Or HTTP-Code: 400 Response-Text: You have already used that password in the past, please choose a new password.

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 Token=... // Autologin Token
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. Or HTTP-Code: 400 Response-Text: Password is too long, it must be {maximum} or less characters long. Or HTTP-Code: 400 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.

EveryRESTFulAPI

This website uses cookies