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!
Also, they share functionalities between theirs 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:
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
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 |
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 |
{
"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: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 |
---|---|---|---|
User's email | String | Yes | |
password | User's password | String | Yes |
{
"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 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"]
}
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 |
---|---|---|---|
User's email | String | Yes |
{
"system_message": {
"type": "notice",
"content": "user password recovery instructions was successfully sent"
}
}
Very important!
To avoid user enumeration vulnerability there's no error message.
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 |
{
"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: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 |
{
"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"]
}
Myself are services whose the users can change their own password, read their own personal data and update them.
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"]
}
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 |
New user's email | String | No | |
locale | New user's locale. Available locales are "pt-BR" and "en" | String | No |
{
"system_message": {
"type": "notice",
"content": "user was successfully updated"
}
}
On error:
{
"system_message": {
"type": "alert",
"content": "user was not updated"
},
"errors": [
...
]
}
Available errors are: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 |
{
"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: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"
}
}
Users are services whose admin users can manage all users.
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 |
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 |
{
"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: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 |
{
"pagination": {
"current_page": 1,
"total_pages": 1,
"total_entries": 1
},
"users": [
... array of users ...
]
}
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"
}
}
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 |
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 |
{
"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: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 |
{
"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: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"
}
}