Introduction

Request Example

$ curl -X POST /
-H "Content-type: application/json"  /
-H "X-ReviewFuel-Key: 2B3A18612CE9F227AF35A94B52983" /
-H "X-ReviewFuel-Token: M9N0iOopesEbi7TnzU7gmcgwg3gWLNbFBhJz3GbVuPgNRKPW9zGo8A2ssuAcxX7o" /
-d '
{
    [JSON Body]...
}'  https://user.reviewfuel.com:9000/resource

Invalid Key/Token Response


HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "errorid":0,
    "errortext":"API Key and Token are not valid for this request."
}

This documentation will keep track of the Review Fuel APIs.

The Review Fuel APIs are built using REST principles which ensures predictable URLs and a small number of objects that can be returned by each service. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API.

Every resource is exposed as a URL. The URL of each resource will be listed in this document.

Each resource will have an API Key and a Token for authentication purposes, and these must be passed in to each API key. These are taken from the custom HTTP headers X-ReviewFuel-Key and X-ReviewFuel-Token

Objects

The API revolves around a number of JSON objects that are either submitted or returned to and from the API end points.

This section will describe those objects.

User Object

JSON User Object


Content-Type:application/json;charset=UTF-8
{
  "id": 0,
  "email": "someuser@someurl.net",
  "password": "!123SomeLongPassword321!",
  "name": "Mike Smith",
  "adminUser": 0,
  "clientUser": 1,
  "sessionToken": "",
  "sessionExpiry": 0
 }

Most calls to the User Service will both require and return a User Object. The User Object contains everything you, or the system, wants to know about the user. This includes:

id: The ID that represents the user in the database, and wiil be useful when calling other services.
email: The Email Address used to log in to the platform
password: The users password. Used only during login.
name: The name of the user.
adminUser: Identified users with administrator level access. This is a boolean value and can be set to either 0 or 1.
clientUser: Identifies that the user is a standard client. This is a boolean value and can be set to either 0 or 1.
sessionToken: The security token which represents this users current session.
sessionExpiry: The timestamp representation of when the users session will expire.

Things To Note

When using the User object, all values must be complete, meaning that often some values are empty strings or set to zero
The adminUser and clientUser variables may soon be merged into a permissions based value.

Password Object

JSON Password Object


Content-Type:application/json;charset=UTF-8
{
  "id": 101,
  "oldPassword": "!123SomeLongPassword321!",
  "newPassword": "321!SomeLongPassword!123",
  "sessionToken": "95d46ac6-2117-4f27-8807-22a555586c5a"
 }

All calls to the User Service password reset endpoint will require a Password object and return a User Object. Everything is mandatory in the Password object

id: The ID that represents the user in the database, and wiil be used to validate the ID.
oldPasword: In use with the above to make sure the old password matches for this user.
newPassword: The new password that will be put in place of the old password.
sessionToken: The session token of the user, to verify that they are currently logged in.

Things To Note

When using the Password object, all values must be complete.
There will be a seperate object for forgotten passwords. This object is only for when the user themselves is updating their password..

User Service

User Service API Endpoint

https://user.reviewfuel.com:9000

The User Service takes care of user actions. These include User creation and updating, logging in, session validation, and password reset

The User Service, generall speaking, performs operations with the User Object. This object is passed in with the required values depending on the operation

Create User

Request Example

$ curl -X POST /
-H "Content-type: application/json"  /
-H "X-ReviewFuel-Key: 2B3A18612CE9F227AF35A94B52983" /
-H "X-ReviewFuel-Token: M9N0iOopesEbi7TnzU7gmcgwg3gWLNbFBhJz3GbVuPgNRKPW9zGo8A2ssuAcxX7o" /
-d '
{
    "id":0,
    "email":"newuser@whatevers.com",
    "password":"somenicelongpassword",
    "name":"New User",
    "adminUser":0,
    "clientUser":1,
    "sessionToken":"",
    "sessionExpiry":0
}'  https://user.reviewfuel.com:9000/user

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "id":101,
    "email":"newuser@whatevers.com",
    "password":"",
    "name":"New User",
    "adminUser":0,
    "clientUser":1,
    "sessionToken":"",
    "sessionExpiry":0
}

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "errorid":1,
    "errortext":"Cannot create a user account. This email address already exists in our system."
}

Creating a User is done by POSTing the User object to the /user endpoint.

When creating a new user, the User Object must contain the values mandated below.

Value	Requirements
`id`	Not Required, but must be included in the submitted JSON. Set to `0`
`email`	Required.
`password`	Required.
`Name`	Required.
`adminUser`	Required. 1 or 0.
`clientUser`	Required. 1 or 0.
`sessionToken`	Not Required, but must be included in the submitted JSON. Set to `""`
`sessionExpiry`	Not Required, but must be included in the submitted JSON. Set to `0`

Things To Note

This call will also create an entry in the Session table, but it will not log the user in. The User object returned from this API can be resubmitted to the login endpoint, along with a password value.
The adminUser and clientUser variables may soon be merged into a permissions based value.

Possible Errors

Error code 1 - Cannot create user account. This email address already exists in our system.
Error code 3 - Cannot create user account. Possible databse problems.
Error code 20 - Caannot create user account. Failed to create entry into the session table
Error code 100 (JSON Values missing)- This will warn if there is no Email, Password, Name, or Permissions

Update User

Request Example

$ curl -X PUT /
-H "Content-type: application/json"  /
-H "X-ReviewFuel-Key: 2B3A18612CE9F227AF35A94B52983" /
-H "X-ReviewFuel-Token: M9N0iOopesEbi7TnzU7gmcgwg3gWLNbFBhJz3GbVuPgNRKPW9zGo8A2ssuAcxX7o" /
-d '
{
    "id":101,
    "email":"newuser@whatevers.com",
    "password":"somenicelongpassword",
    "name":"New Name",
    "adminUser":1,
    "clientUser":0,
    "sessionToken":"95d46ac6-2117-4f27-8807-22a555586c5a",
    "sessionExpiry":1010101010
}'  https://user.reviewfuel.com:9000/user

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "id":101,
    "email":"newuser@whatevers.com",
    "password":"",
    "name":"New Name",
    "adminUser":1,
    "clientUser":0,
    "sessionToken":"95d46ac6-2117-4f27-8807-22a555586c5a",
    "sessionExpiry":1010101010
}

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "errorid":21,
    "errortext":"Cannot update a user account. Failed to retrieve session data."
}

Updating a User is done by PUTing the modified User object to the /user endpoint.

When updating a user account, the User Object must contain the values mandated below.

Value	Requirements
`id`	Required. This will validate the user against their session.
`email`	Required.
`password`	Required.
`Name`	Required.
`adminUser`	Required. 1 or 0.
`clientUser`	Required. 1 or 0.
`sessionToken`	Required. A User must be logged in in order to update their details.
`sessionExpiry`	Not Required, but must be included in the submitted JSON. Set to `0`

Things To Note

The User object requires a Session Token in order to validate that the user is logged in. A user must be logged in to change their details.
There will be, in future, different tools to govern access for administrative users for updating accounts.

Possible Errors

Error code 5 - Cannot update user account. Failed to updare user account details in the database.
Error code 21 - Cannot update user account. Failed to retrieve their session data.
Error code 20 - Caannot create user account. Failed to create entry into the session table
Error code 100 (JSON Values missing)- This will warn if there is no Email, Password, Name, Permissions, or Session Token

Request Example

$ curl -X POST /
-H "Content-type: application/json"  /
-H "X-ReviewFuel-Key: 2B3A18612CE9F227AF35A94B52983" /
-H "X-ReviewFuel-Token: M9N0iOopesEbi7TnzU7gmcgwg3gWLNbFBhJz3GbVuPgNRKPW9zGo8A2ssuAcxX7o" /
-d '
{
    "id":0,
    "email":"newuser@whatevers.com",
    "password":"somenicelongpassword",
    "name":"",
    "adminUser":0,
    "clientUser":0,
    "sessionToken":"",
    "sessionExpiry":0
}'  https://user.reviewfuel.com:9000/login

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "id":101,
    "email":"newuser@whatevers.com",
    "password":"",
    "name":"New Name",
    "adminUser":1,
    "clientUser":0,
    "sessionToken":"95d46ac6-2117-4f27-8807-22a555586c5a",
    "sessionExpiry":1010101010
}

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "errorid":100,
    "errortext":"No Password Provided. No Email Provided"
}

Updating a User is done by POSTing the modified User object to the /login endpoint.

When logging a user in, the User Object must contain the values mandated below.

Value	Requirements
`id`	Not Required, but must be included in the submitted JSON. Set to `0`
`email`	Required.
`password`	Required.
`Name`	Not Required, but must be included in the submitted JSON. Set to ""
`adminUser`	Not Required, but must be included in the submitted JSON. Set to `0`
`clientUser`	Not Required, but must be included in the submitted JSON. Set to `0`.
`sessionToken`	Not Required, but must be included in the submitted JSON. Set to ""
`sessionExpiry`	Not Required, but must be included in the submitted JSON. Set to `0`

The User object requires a Session Token in order to validate that the user is logged in. A user must be logged in to change their details.
There will be, in future, different tools to govern access for administrative users for updating accounts.

Error code 2 - Cannot log in. Invalid username or password.
Error code 22 - Cannot log in. Failed to update SessionID for user.
Error code 100 (JSON Values missing)- This will warn if there is no Emailor Password

Password Reset

Request Example

$ curl -X POST /
-H "Content-type: application/json"  /
-H "X-ReviewFuel-Key: 2B3A18612CE9F227AF35A94B52983" /
-H "X-ReviewFuel-Token: M9N0iOopesEbi7TnzU7gmcgwg3gWLNbFBhJz3GbVuPgNRKPW9zGo8A2ssuAcxX7o" /
-d '
{
  "id": 101,
  "oldPassword": "!123SomeLongPassword321!",
  "password": "321!SomeLongPassword!123",
  "sessionToken": "95d46ac6-2117-4f27-8807-22a555586c5a"
 }'  https://user.reviewfuel.com:9000/passwordreset

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "id":101,
    "email":"newuser@whatevers.com",
    "password":"",
    "name":"New Name",
    "adminUser":1,
    "clientUser":0,
    "sessionToken":"95d46ac6-2117-4f27-8807-22a555586c5a",
    "sessionExpiry":1010101010
}

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "errorid":21,
    "errortext":"Cannot reset password. Failed to retrieve session data"
}

Updating a users Password is done by POSTing the modified Password object to the /passwordreset endpoint.

When resetting a users password, the Password Object must contain the values mandated below.

Value	Requirements
`id`	Required to make sure the password matces the right user
`oldPassword`	Required to make sure the user is resetting their own password
`newPassword`	Required. This will be the users new password
`sessionToken`	Required to make sure the user is logged in while resetting their password

The Password object requires a Session Token in order to validate that the user is logged in. A user must be logged in to change their details.
This is not the same as the ForgottenPassword object. This is not part of the forgotten password workflow..

Possible Errors

Error code 4 - Cannot reset password. Old password incorrect.
Error code 6 - Cannot reset password. New or Old password not supplied in payload.
Error code 21 - Cannot reset password. Failed to retrieve session data.

Validate Session

Request Example

$ curl -X POST /
-H "Content-type: application/json"  /
-H "X-ReviewFuel-Key: 2B3A18612CE9F227AF35A94B52983" /
-H "X-ReviewFuel-Token: M9N0iOopesEbi7TnzU7gmcgwg3gWLNbFBhJz3GbVuPgNRKPW9zGo8A2ssuAcxX7o" /
-d '
{
    "id":0,
    "email":"",
    "password":"",
    "name":"",
    "adminUser":0,
    "clientUser":0,
    "sessionToken":"95d46ac6-2117-4f27-8807-22a555586c5a",
    "sessionExpiry":0
}'  https://user.reviewfuel.com:9000/validatesession

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "id":101,
    "email":"newuser@whatevers.com",
    "password":"",
    "name":"New Name",
    "adminUser":1,
    "clientUser":0,
    "sessionToken":"95d46ac6-2117-4f27-8807-22a555586c5a",
    "sessionExpiry":1010101010
}

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "errorid":100,
    "errortext":"No Session Token was supplied"
}

Getting a valid User from their session id (cookie login) is done by POSTing the modified User object to the /validatesession endpoint.

When validating a session, the User Object must contain the values mandated below.

Value	Requirements
`id`	Not Required, but must be included in the submitted JSON. Set to `0`
`email`	Not Required, but must be included in the submitted JSON. Set to ""
`password`	Not Required, but must be included in the submitted JSON. Set to ""
`Name`	Not Required, but must be included in the submitted JSON. Set to ""
`adminUser`	Not Required, but must be included in the submitted JSON. Set to `0`
`clientUser`	Not Required, but must be included in the submitted JSON. Set to `0`.
`sessionToken`	Required.
`sessionExpiry`	Not Required, but must be included in the submitted JSON. Set to `0`

Things To Note

This is used to keep people logged in. The session id (or some key/value there of) should be stored in a cookie.

Possible Errors

Error code 21 - Cannot validate session. Failed to retrieve session data for session {sessionId]
Error code 100 (JSON Values missing)- This will warn if there is no sessionToken

Introduction

Objects

User Object

Things To Note

Password Object

Things To Note

User Service

Create User

Things To Note

Possible Errors

Update User

Things To Note

Possible Errors

Login

Things To Note

Possible Errors

Password Reset

Things To Note

Possible Errors

Validate Session

Things To Note

Possible Errors