Models¶

Paths and Views in Morepath are bound to a Model. So we will use the Model names as chapters in the API documentation. Each model is bound to a Path and has related View method(s).

The permissions are defined in server/permissions.py.

Details about the Cerberus schemas used by the views can be found in server/schema.yml.

Root¶

Path: '/'

GET method¶

Returns a dictionary of available collections and there entry points.

Permission: None

Example request:

http.get('/')

Responses¶

200 - OK¶

Example response JSON:

{
    "collections": {
        "users": {
            "@id": "/users"
        },
        "groups": {
            "@id": "/groups"
        }
    }
}

UserCollection¶

Path: '/users'

GET method¶

Returns a list of user entities and if pagination is enabled the number of total pages. The query can be searched, sorted and paginated. The search applies on nickname and email.

Permission: ViewPermission

Example request:

http.get('/users', {
  search: 'Marie',  // caseinsensitive, uses nickname and email fields
  sortby: 'nickname',
  sortdir: 'desc',  // default: 'asc'
  page: 4,  // 0 disables pagination
  pagesize: 5
}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Example response JSON:

{
  "users": [
    {
      "@id": "/users/1",
      "nickname": "Leader",
      "email": "leader@example.com",
      "emailConfirmed": true,
      "isAdmin": true,
      "lastLogin": "2017-04-30 15:42:57",
      "registered": "2017-04-20 23:04:27",
      "registerIP": "127.0.0.1",
    }, {
      "@id": "/users/2",
      "nickname": "Marie",
      "email": "marie@example.com",
      "emailConfirmed": false,
      "isAdmin": false,
      "lastLogin": "2017-04-30 14:38:25",
      "registered": "2017-04-27 20:05:57",
      "registerIP": "127.0.0.1",
    }
  ],
  "pages": 5
}

POST method¶

Add a new user. Use on registration. A confirm email is sent to the email address.

Permission: None

Validation schema: user

Example request:

http.post('/users', {
  nickname: 'Marie',
  email: 'marie@example.com',
  password: 'Secret0'
})

Responses¶

201 - Created¶

User created successfully.

Response JSON: empty

Signal emitted: user.email_updated

409 - Conflict¶

Email address already exists.

Response JSON:

{
  "validationError": "Email already exists"
}

422 - Unprocessable Entity¶

Validation error either from EmailValidationService or from Cerberus schema validation.

Response JSON from EmailValidationService when email address is not valid:

{
  "email": ["Not valid email"]
}

Response JSON from EmailValidationService when email domain cannot be found:

{
  "email": ["Email could not be delivered"]
}

Example response JSON from Cerberus when schema is not valid:

{
  "nickname": ["must be of string type"]
}

User¶

Path: '/users/{id}'

GET method¶

Returns the user entity with the requested id.

Permission: ViewPermission

Example request:

http.get('/users/1', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Example response JSON:

{
  "@id": "/users/1",
  "nickname": "Leader",
  "email": "leader@example.com",
  "emailConfirmed": true,
  "isAdmin": true,
  "lastLogin": "2017-04-30 15:42:57",
  "registered": "2017-04-20 23:04:27",
  "registerIP": "127.0.0.1",
}

PUT method¶

Update a user entity with the fields which are provided. Other fields stay untouched.

If the email field is updated, the email_confirmed field is set to False and a confirm email is sent to the new email address.

Permission: EditPermission

Validation schema: user

Example request:

http.put('/users/1', {
  nickname: 'Marie',
  email: 'marie@example.com'
}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

User updated successfully.

Response JSON: empty

Signal emitted when email was updated: user.email_updated

409 - Conflict¶

Email address already exists.

Response JSON:

{
  "validationError": "Email already exists"
}

422 - Unprocessable Entity¶

Validation error either from EmailValidationService or from Cerberus schema validation.

Response JSON from EmailValidationService when email address is not valid:

{
  "email": ["Not valid email"]
}

Response JSON from EmailValidationService when email domain cannot be found:

{
  "email": ["Email could not be delivered"]
}

Example response JSON from Cerberus when schema is not valid:

{
  "nickname": ["must be of string type"]
}

DELETE method¶

Delete a user entity.

Permission: EditPermission

Example request:

http.delete('/users/1', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

User deleted successfully.

Response JSON: empty

Login¶

Path: '/login'

POST method¶

Log in the user and return a JWT token in the Authorization header.

Permission: None

Validation schema: login

Example request:

http.post('/login', {
  email: "test@example",
  password: "secret"
})

Responses¶

200 - OK¶

User successfully logged in.

Response JSON: empty

Response Headers: 'Authorization': jwt_token

403 - Forbidden¶

Invalid credentials.

Response JSON:

{
  "validationError": "Invalid email or password"
}

422 - Unprocessable Entity¶

Validation error from Cerberus schema validation.

Example response JSON when schema is not valid:

{
  "password": ["min length is 5"]
}

Refresh¶

Path: '/refresh'

GET method¶

Receives an expired or nearly expired JWT token in the request Authorization header and returns a refreshed JWT token in the response Authorization header.

Permission: None

Example request:

http.get('/refresh', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Token successfully refreshed.

Response JSON: empty

Response Headers: 'Authorization': jwt_token

403 - Forbidden¶

The JWT token could not be refreshed.

Response JSON when refresh_until or token has expired:

{
  "validationError": "Your session has expired"
}

Response JSON when token could not be refreshed:

{
  "validationError": "Could not refresh your token"
}

ResetNonce¶

Path: 'users/{id}/signout'

GET method¶

Reset the refresh nonce of the user with the given id.

Permission: None

Example request:

http.get('/users/1/signout', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

The refresh nonce successfully reset so all current JWT tokens of this user cannot be refreshed anymore.

Response JSON: empty

ConfirmEmail¶

Path: 'users/{id}/confirm/{token}'

GET method¶

Confirm the email address of the user with the given id. The link is sent from the user.email_updated signal to the users email address which should be confirmed. It contains a token which is generated from TokenService and contains a time-limit which can be adjusted in the token.max_age setting.

Permission: EditPermission

Example request:

http.get(
  '/users/4/confirm/Im5ld3VzZXJAZXhhbXBsZS5jb20i.C3dnsw.2meomRPK3wnYwB2AERt2ygjFaRE'
)

Responses¶

302 - Found¶

After processing the request it redirects to the homepage. Examples here are in Python language.

Example redirect URL when email address is successfully confirmed:

from base64 import urlsafe_b64encode


flash = urlsafe_b64encode(
    'Thank you for confirming your email address'.encode('utf-8')
).replace(b'=', b'').decode('utf-8')

url = "http://yourawesomesite.com/?flashtype=success&flash=" + flash

Example redirect URL when email address was already confirmed before:

flash = urlsafe_b64encode(
    'Your email is already confirmed. Please log in.'.encode('utf-8')
).replace(b'=', b'').decode('utf-8')

url = "http://yourawesomesite.com/?flashtype=info&flash=" + flash

Example redirect URL when email address could not be confirmed:

flash = urlsafe_b64encode(
    'The confirmation link is invalid or has been expired'.encode('utf-8')
).replace(b'=', b'').decode('utf-8')

url = "http://yourawesomesite.com/?flashtype=error&flash=" + flash

SendResetEmail¶

Path: '/reset'

POST method¶

Send a password reset email to given email address.

Permission: None

Validation schema: send_reset_email_validator

Example request:

http.post('/reset', {
  email: 'marie@example.com'
})

Responses¶

200 - OK¶

Password reset email successfully sent.

Response JSON: empty

403 - Forbidden¶

Email not in database or email address not yet confirmed.

Response JSON when email not in database:

{
  "validationError": "Email not found"
}

Response JSON when email address not yet confirmed:

{
  "validationError": "Your email must be confirmed before resetting the password."
}

422 - Unprocessable Entity¶

Validation error from Cerberus schema validation.

Example response JSON when schema is not valid:

{
  "email": ["must be of string type"]
}

ResetPassword¶

Path: 'users/{id}/reset/{token}'

GET method¶

Allows the user with given id to reset his password. The link is sent from the MailerService to the users email address if it was confirmed before. It contains a token which is generated from TokenService and contains a time-limit which can be adjusted in the token.max_age setting.

Permission: None

Example request:

http.get(
  '/users/7/reset/Im5ld3VzZXJAZXhhbXBsZS5jb20i.C40RUQ.5JhlEE36_JrUGhlAxao46VsQevI'
)

Responses¶

302 - Found¶

After processing the request it redirects on success to '/newpassword' and on error to '/login'. Examples here are in Python language.

Example redirect URL when reset password request was excepted:

url = "http://yourawesomesite.com/newpassword?%40id=%2Fusers%2F7%2Freset%2F" +
      "Im5ld3VzZXJAZXhhbXBsZS5jb20i.C40RUQ.5JhlEE36_JrUGhlAxao46VsQevI"

Example redirect URL when reset link is invalid:

flash = urlsafe_b64encode(
    'The password reset link is invalid or has been expired'.encode('utf-8')
).replace(b'=', b'').decode('utf-8')

url = "http://yourawesomesite.com/login?flashtype=error&flash=" + flash

PUT method¶

Reset the password of the user with given id to the provided password.

Permission: None

Validation schema: reset_password

Example request:

http.put(
  '/users/7/reset/Im5ld3VzZXJAZXhhbXBsZS5jb20i.C40RUQ.5JhlEE36_JrUGhlAxao46VsQevI',
  {
    password: 'NewSecret'
  }
)

Responses¶

200 - OK¶

Password resetted successfully.

Response JSON: empty

403 - Forbidden¶

Email not in database or email address not yet confirmed.

Response JSON when reset token is invalid:

{
  "validationError": "The password reset link is invalid or has been expired"
}

Response JSON when email address not yet confirmed:

{
  "validationError": "Your email must be confirmed before resetting the password."
}

422 - Unprocessable Entity¶

Validation error from Cerberus schema validation.

Example response JSON when schema is not valid:

{
  "password": ["min length is 5"]
}

GroupCollection¶

Path: '/groups'

GET method¶

Returns a list of group entities.

Permission: ViewPermission

Example request:

http.get('/groups', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Example response JSON:

{
  "groups": [
    {
      "@id": "/groups/1",
      "name": "Admin",
      "users": ["leader@example.com"]
    }, {
      "@id": "/groups/2",
      "name": "Moderator",
      "users": ["marie@example.com"]
    }
  ]
}

POST method¶

Add a new group.

Permission: EditPermission

Validation schema: group

Example request:

http.post('/groups', {
  name: 'Editor'
})

Responses¶

201 - Created¶

Group created successfully.

Response JSON:

{
  "@id": "/groups/4"
}

409 - Conflict¶

Group name already exists.

Response JSON:

{
  "validationError": "Group already exists"
}

422 - Unprocessable Entity¶

Validation error from Cerberus schema validation.

Example response JSON from Cerberus when schema is not valid:

{
  "name": ["must be of string type"]
}

Group¶

Path: '/groups/{id}'

GET method¶

Returns the group entity with the requested id.

Permission: ViewPermission

Example request:

http.get('/groups/1', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Example response JSON:

{
  "@id": "/groups/1",
  "name": "Admin",
  "users": ["leader@example.com"]
}

PUT method¶

Update a group entity with the fields which are provided. Other fields stay untouched.

Permission: EditPermission

Validation schema: group

Example request:

http.put('/groups/1', {
  name: 'Editor'
}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Group updated successfully.

Response JSON: empty

409 - Conflict¶

Group already exists.

Response JSON:

{
  "validationError": "Group already exists"
}

422 - Unprocessable Entity¶

Validation error from Cerberus schema validation.

Example response JSON from Cerberus when schema is not valid:

{
  "name": ["must be of string type"]
}

DELETE method¶

Delete a group entity.

Permission: EditPermission

Example request:

http.delete('/groups/1', {}, {
  headers: {'Authorization': jwt_token}
})

Responses¶

200 - OK¶

Group deleted successfully.

Response JSON: empty