wheel doc

1 Overview

When we create a new API with Wheel, it generates by default three resources: Sessions, Myself and Users. Each one has its own routes (check file /app/root/path/routes/routes.go) and access permissions (check file /app/root/path/routes/authorization.go).

Quick tips!

To learn more about routes check the routes section.
To learn more about access permissions check the authorization section.

Also, they share functionalities between theirs models, views and handlers.

Quick tip!

Check the internals sections for models, views and handlers.

To test the API resources, we recommend you to use the Postman client software. But feel free to choose another similar tool.

If you didn't change the default admin credentials, here they are:

email	user@example.com
password	Secret123!

Very important!

Use these credentials, above, to sign in as an admin user. Make sure you already have ran the migration.

$> go run main.go -mode=migrate

2 Sessions

Sessions manage user's access to the API. Its services are: sign up, sign in, sign out, password recovery and session refresh.

The public of the internet can sign up, but they can't sign up as an admin user.

Only an admin user can create others admins. We are going to deep in details at Users section.

POST /sessions/sign_up

Payload:


curl -X POST -H 'Content-Type: application/json' \
    -d '{ \
        "name": "Your Name", \
        "email":"your.email@example.com", \ 
        "password":"Secret123!", \
        "locale":"en" \
      }' \
    http://localhost:8081/sessions/sign_up

Parameters:

Name	Description	Type	Required
name	New user's name	String	Yes
email	New user's email	String	Yes
password	New user's password	String	Yes
locale	New user's locale. Available locales are "pt-BR" and "en"	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "signed in successfully"
    },
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9....",
    "expires": 7200
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user was not created"
    },
    "errors": [
    ...
    ]
}

Available errors are:

name can't be blank
name is too long
email can't be blank
email is too long
email is invalid
email has already been taken
password is too short minimum is 8 characters
locale is invalid

Users with a valid credential can sign in the system. Upon successful sign in, the user will recieve a JWT-based token and an expiration time in seconds. It means that you need to provide the token in furthers requests to get access. Be aware to update the token before it get expired calling the session refresh service.

POST /sessions/sign_in

Payload:


curl -X POST -H 'Content-Type: application/json' \
    -d '{ \
        "email":"your.email@example.com", \ 
        "password":"Secret123!", \
      }' \
    http://localhost:8081/sessions/sign_in

Parameters:

Name	Description	Type	Required
email	User's email	String	Yes
password	User's password	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "signed in successfully"
    },
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9....",
    "expires": 7200
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "could not sign in"
    },
    "errors": ["invalid credentials"]
}

Sign Out

Sign out for signed in users.

DELETE /sessions/sign_out

Payload:


curl -X DELETE -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081/sessions/sign_out

On success:


{
  "system_message": {
    "type":"notice",
    "content":"signed out successfully"
  }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "access denied"
    },
    "errors": ["invalid token"]
}

Request Password Recovery

Kick off to password recovery.

The target user will receive an email with the instructions.

POST /sessions/password

Payload:


curl -X POST -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{ \
        "email":"your.email@example.com" \ 
      }' \
    http://localhost:8081/sessions/password

Parameters:

Name	Description	Type	Required
email	User's email	String	Yes

On success or on error:


{
    "system_message": {
        "type": "notice",
        "content": "user password recovery instructions was successfully sent"
    }
}

Very important!

To avoid user enumeration vulnerability there's no error message.

Password Recovering

Confirms password recovery.

PUT /sessions/password

Payload:


curl -X PUT -H 'Content-Type: application/json' \
    -d '{ \
        "token": "jksdfn983489jd9832mksd09", \
        "new_password":"Secret.456", \ 
        "password_confirmation":"Secret.456" \
      }' \
    http://localhost:8081/sessions/password

Parameters:

Name	Description	Type	Required
token	Recovery passoword token	String	Yes
new_password	New password	String	Yes
password_confirmation	Password confirmation	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "password was successfully changed"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "password could not be changed"
    },
    "errors": [
    ...
    ]
}

Available errors are:

invalid reset password token
password confirmation does not match new password
password is too short minimum is 8 characters

Session Refresh

Refreshes the session. Returns a new JWT-based token and a new expiration time in seconds.

POST /sessions/refresh

Payload:


curl -X POST -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081/sessions/refresh

Parameters:

Name	Description	Type	Required
token	Session token	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "session was successfully refreshed"
    },
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": 7200
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "access denied"
    },
    "errors": ["invalid token"]
}

3 Myself

Myself are services whose the users can change their own password, read their own personal data and update them.

Read

Returns current user's personal data.

GET /myself

Payload:


curl -X GET -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081/myself

On success:


{
    "id": 1,
    "name": "User Name",
    "email": "user@example.com",
    "created_at": "2019-08-08T01:21:37.351901Z",
    "updated_at": "2019-08-08T01:21:37.351901Z"
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "access denied"
    },
    "errors": ["invalid token"]
}

Update

Updates current user's personal data.

PUT /myself

Payload:


curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{ \
        "name" : 'My New Name', \
        "email" : 'my.new.email@example.com', \
        "locale" : 'en' \
      }'
    http://localhost:8081/myself

Parameters:

Name	Description	Type	Required
name	New user's name	String	No
email	New user's email	String	No
locale	New user's locale. Available locales are "pt-BR" and "en"	String	No

On success:


{
    "system_message": {
        "type": "notice",
        "content": "user was successfully updated"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user was not updated"
    },
    "errors": [
    ...
    ]
}

Available errors are:

name can't be blank
name is too long
email can't be blank
email is too long
email is invalid
email has already been taken
locale is invalid

Update password

Updates current user's password.

PUT /myself/password

Payload:


curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{ \
        "new_password":"Secret.789", \ 
        "password_confirmation":"Secret.789" \
      }' \
    http://localhost:8081/myself/password

Parameters:

Name	Description	Type	Required
new_password	New password	String	Yes
password_confirmation	Password confirmation	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "password was successfully changed"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "password could not be changed"
    },
    "errors": [
    ...
    ]
}

Available errors are:

password confirmation does not match new password
password is too short minimum is 8 characters

Destroy

Destroys current user.

DELETE /myself

Payload:


curl -X DELETE -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081/myself

On success:


{
    "system_message": {
        "type": "notice",
        "content": "user was successfully destroyed"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user could not be destroyed"
    }
}

4 Users

Users are services whose admin users can manage all users.

Create

Creates new users.

POST /users

Payload:


curl -X POST -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{ \
        "name": "New User Name", \
        "email":"new.user.email@example.com", \ 
        "password":"Secret.001", \ 
        "admin":"false", \
        "locale":"en" \
      }' \
    http://localhost:8081/users

Parameters:

Name	Description	Type	Mandatory
name	User's name	String	Yes
email	User's email	String	Yes
password	User's password	String	Yes
admin	"true" for admin users and "false" for non admin users. Default is "false".	Boolean	No
locale	User's locale. Available locales are "en" or "pt-BR"	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "user was successfully created"
    },
    "user": {
        "id": "user's id",
        "name": "New User Name",
        "email": "new.user.email@example.com",
        "admin": false,
        "locale": "en",
        "created_at": "2019-08-26T23:30:26.820820046Z",
        "updated_at": "2019-08-26T23:30:26.820820046Z"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user was not created"
    },
    "errors": [
    ...
    ]
}

Available errors are:

name can't be blank
name is too long
email can't be blank
email is too long
email is invalid
email has already been taken
password is too short minimum is 8 characters
locale is invalid

List

Lists registered users.

GET /users

Payload:


curl -X GET -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081/users

Paramenters:

Name	Description	Type	Required
page	Page number. Default is 1	Integer	No
per_page	Entries per page. Default is 20	Integer	No
order	List ordering	String	No
search[...]	Example: use search[name_cont]=a to search users whose contain "a" in their name. More than one parameter search is allowed. To learn more about it, check the search engine section.	String	No

On success:


{
    "pagination": {
        "current_page": 1,
        "total_pages": 1,
        "total_entries": 1
    },
    "users": [
          ... array of users ...
    ]
}

Show

Shows one single user, per once, identified by an id.

GET /users/{id}

Payload:


curl -X GET -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081/users/1

On success:


{
      "id": "user's ID",
      "name": "user's name",
      "email": "user's email",
      "password": "user's password",
      "admin": true or false,
      "locale": "user's locale",
      "created_at": "2019-08-26T23:30:26.820820046Z",
      "updated_at": "2019-08-26T23:30:26.820820046Z"
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user was not found"
    }
}

Update

Updates one single user, per once, identified by an id.

PUT /users/{id}

Payload:


curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{ \
        "name": "User Name", \
        "email": "user.email@example.com", \ 
        "admin": "false", \
        "locale": "en" \
      }' \
    http://localhost:8081/users/1

Parameters:

Name	Description	Type	Mandatory
name	User's name	String	Yes
email	User's email	String	Yes
admin	"true" for admin users and "false" for non admin users. Default is "false".	Boolean	No
locale	User's locale. Available locales are "en" or "pt-BR"	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "user was successfully updated"
    },
    "user": {
        "id": "user's ID",
        "name": "user's name",
        "email": "user's email",
        "admin": true or false,
        "locale": "user's locale",
        "created_at": "2019-08-26T23:30:26.820820046Z",
        "updated_at": "2019-08-26T23:30:26.820820046Z"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user was not updated"
    },
    "errors": [
    ...
    ]
}

Available errors are:

name can't be blank
name is too long
email can't be blank
email is too long
email is invalid
email has already been taken
password is too short minimum is 8 characters
locale is invalid

Update Password

Updates one single user's password, per once, identified by an id.

PUT /users/{id}/password

Payload:


curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{ \
        "password": "User Name" \
      }' \
    http://localhost:8081/users/1/password

Parameters:

Name	Description	Type	Mandatory
password	User's password	String	Yes

On success:


{
    "system_message": {
        "type": "notice",
        "content": "user password was successfully updated"
    },
    "user": {
        "id": "user's ID",
        "name": "user's name",
        "email": "user's email",
        "admin": true or false,
        "locale": "user's locale",
        "created_at": "2019-08-26T23:30:26.820820046Z",
        "updated_at": "2019-08-26T23:30:26.820820046Z"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user password was not updated"
    },
    "errors": [
    ...
    ]
}

Available errors are:

name can't be blank
name is too long
email can't be blank
email is too long
email is invalid
email has already been taken
password is too short minimum is 8 characters
locale is invalid

Destroy

Detroys one single user, per once, identified by an id.

DELETE /users/{id}

Payload:


curl -X DELETE -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    http://localhost:8081//users/1

On success:


{
    "system_message": {
        "type": "notice",
        "content": "user was successfully destroyed"
    }
}

On error:


{
    "system_message": {
        "type": "alert",
        "content": "user was not found"
    }
}

Wheel Doc

Default Resources

1 Overview

2 Sessions

3 Myself

4 Users

Getting Started

Default Resources

Code Generator

Internals

Features

Wheel Doc

Default Resources

1 Overview

2 Sessions

3 Myself

4 Users