popphp/kettle-user

1.0.0 2017-05-18 21:18 UTC

README

kettle-user is a simple user REST API. It allows for client applications to manage users and user data. It supports user types and their associated schemas, as well as user roles. It also uses the kettle-auth authentication API to authenticate users with the kettle-user API.

The Kettle Namespace is a set of tools built using components from the Pop PHP Framework.

Requirements

The client application that is interfacing with the kettle-user API would also interface with the kettle-auth API to authenticate a user and obtain a token. That token can then be passed to the kettle-user API on each request and it will validate the token on each request with the kettle-auth API server.

Top

Installation

kettle-users comes with the database schemas for MySQL, PostgreSQL and SQLite. Load the preferred schema into your database, and copy the file app/config/app.web.orig.php to app/config/app.web.php and load the corresponding database credentials into the new config file. Also, enter the URL of the authentication server that is running the kettle-auth authentication API.

For the examples below, the PHP CLI server is used at http://localhost:8000/. Please note, it is strongly recommended that you use https in production.

Top

User Types

The purpose of user types is to create a 1:1 relationship between a type of user and a set of common data for that user type. For example, you may users of different types that require store different data points for them. You may have a user type staff that requires the data fields of first_name, last_name and email. Then you may have a user type of customer that requires the data fields of contact_name, company, phone, website.

Top

Creating User Types

To create a user type and its associated schema:

curl -i -X PUT --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
   -d"type=staff&field_name_1=first_name&field_name_2=last_name&field_name_3=email" \
   http://localhost:8000/types
HTTP/1.1 201 Created
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "type": "staff"
}

The above request and response show that new user type of staff has been created. Furthermore, if you look at the database, a new table has been created called user_type_staff, which contains the foreign key user_id and the data fields of first_name, last_name and email. Now, all users of the type staff will have their data stored to and retrieved from this table.

Top

Listing User Types

To list the available user types:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/types
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "types": [
        {
            "id": 1,
            "type": "staff"
        }
    ]
}

To list a single user type:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/types/1
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "type": "staff"
}

Top

Updating a User Type

You can update a user type like this:

curl -i -X POST --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"type=staff2" http://localhost:8000/types/1
HTTP/1.1 200 Updated
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "type": "staff2"
}

If you change the user type name, the table will be updated to reflect that change. You can also update the user type's schema as well, and that is covered in the section below User Type Schemas.

Top

Deleting User Types

You can delete a single user type like this:

curl -i -X DELETE --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/types/1

Or, delete multiple user types at once like this:

curl -i -X DELETE --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"type_ids[]=1&type_ids[]=2" http://localhost:8000/types

Both requests will return:

HTTP/1.1 204 Deleted
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

Top

User Type Schemas

Above, there is a small example of quickly creating a user type with a schema of a few simple fields. When done in that way, the field type defaults to VARCHAR. However, you can have greater control and flexibility over the schema. First, if the schema you wish to create is more complex, you can create it on a second, separate request. So you could create only the user type first:

curl -i -X PUT --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
   -d"type=staff" http://localhost:8000/types

And then send a request that will define and create the schema for that user type:

curl -i -X PUT --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
    -d"field_name_1=first_name" \
    -d"field_type_1=varchar" \
    -d"field_size_1=255" \
    -d"field_name_2=last_name" \
    -d"field_type_2=varchar" \
    -d"field_size_2=255" \
    -d"field_name_3=email" \
    -d"field_type_3=varchar" \
    -d"field_size_3=255" \
    -d"field_name_4=logins" \
    -d"field_type_4=integer" \
    -d"field_size_4=16" \
    -d"field_name_5=birth_date" \
    -d"field_type_5=date" \
    http://localhost:8000/types/schema/1

In the above example, you can send up to four entries of data across per field (the # represents the number of the entry referenced):

  • field_name_#
  • field_type_#
  • field_size_# (where applicable)
  • field_precision_# (where applicable)

The field types supported are:

  • integer
  • float
  • decimal
  • double
  • varchar
  • text
  • date
  • time
  • datetime

Using the above convention, you can create more complex and in-depth schemas to capture and store specific user data for a user type.

Top

Updating the Schema

You can update the schema as well, adding new fields or renaming existing ones. Adding new fields follows the same convention above. Renaming a field uses the convention of field_old_name_# and field_new_name_#. And updating the schema is done using POST:

curl -i -X POST --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
    -d"field_old_name_1=logins" \
    -d"field_new_name_1=user_logins" \
    -d"field_name_2=address" \
    http://localhost:8000/types/schema/1

The above request renamed the field logins to user_logins and added a new field for address.

Top

Deleting from the Schema

And deleting from the schema is handled in a similar way as creating the schema, just using DELETE:

curl -i -X DELETE --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
    -d"field_name_1=address"  http://localhost:8000/types/schema/1

The above request drops the field address from the schema.

Top

User Roles

The purpose of user roles is to create a 1:many relationship between a user and the various roles that user is assigned. It is possible for a user to be an admin and editor, or any combination of roles that are defined in the application. The roles can be passed to other resource applications for them to evaluate if the current user requesting access to certain resources can be granted access based on their defined roles.

Top

Creating User Roles

curl -i -X PUT --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"role=admin" http://localhost:8000/roles
HTTP/1.1 201 Created
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "role": "admin"
}

Top

Listing User Roles

To list all of the user roles:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/roles
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "roles": [
        {
            "id": 1,
            "role": "admin"
        }
    ]
}

To list a single role:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/roles/1
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "role": "admin"
}

Top

Updating a User Role

curl -i -X POST --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"role=admin2" http://localhost:8000/roles/1
HTTP/1.1 200 Updated
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "role": "admin2"
}

Top

Deleting User Roles

curl -i -X DELETE --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/roles/1
HTTP/1.1 204 Deleted
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

Top

Users

Creating a User

Continuing with the earlier example, let's assume that a user type of staff (id: 1) has been created and has the fields first_name, last_name and email. Also, the roles admin (id: 1) and editor (id: 2) have also been created.

From there you can send a request like this to create a user:

curl -i -X PUT --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"type_id=1" \
  -d"role_ids[]=1" \
  -d"role_ids[]=2" \
  -d"first_name=Test" \
  -d"last_name=Person" \
  -d"email=test@test.com" http://localhost:8000/users
HTTP/1.1 201 Created
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "username": "",
    "active": "",
    "manage": "",
    "type_id": 1,
    "user_id": 1,
    "type": "staff",
    "roles": {
        "1": "admin",
        "2": "editor"
    },
    "first_name": "Test",
    "last_name": "Person",
    "email": "test@test.com"
}

Top

Listing Users

To list all users:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/users

To list all users of a specific user type:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/users?type_id=1

To search for a user by a field:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  "http://localhost:8000/users?type_id=1&first_name=Tes"
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "users": [
        {
            "id": 1,
            "username": "",
            "active": "",
            "manage": "",
            "type_id": 1,
            "user_id": 1,
            "type": "staff",
            "roles": {
                "1": "admin",
                "2": "editor"
            },
            "first_name": "Test",
            "last_name": "Person",
            "email": "test@test.com"
        }
    ]
}

Top

Updating a User

curl -i -X POST --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"first_name=Test2" http://localhost:8000/users/1
HTTP/1.1 200 Updated
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "username": "",
    "active": "",
    "manage": "",
    "type_id": 1,
    "type": "staff",
    "roles": {
        "1": "admin",
        "2": "editor"
    },
    "first_name": "Test2",
    "last_name": "Person",
    "email": "test@test.com"
}

Top

Deleting Users

curl -i -X DELETE --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/users/2
HTTP/1.1 204 Deleted
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

Top

Linking Users

Users can be directly linked to the same user that's authenticating through the kettle-auth API, but it is not required. If a user is not linked to an auth user account, then that user will just represent data in the application and will not be able to authenticate or log into any applications.

In the above examples, the users were not linked, so the values of username, active and manage were empty. However, if you pass a user_id value when creating a user, it will link it to the user record with the authentication API. Knowing that the user admin has a user_id of 1 with the authentication API, you can add the field user_id to the PUT request:

curl -i -X PUT --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  -d"user_id=1" \
  -d"type_id=1" \
  -d"role_ids[]=1" \
  -d"role_ids[]=2" \
  -d"first_name=Test" \
  -d"last_name=Person" \
  -d"email=test@test.com" http://localhost:8000/users
HTTP/1.1 201 Created
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "id": 1,
    "username": "admin",
    "active": 1,
    "manage": 1,
    "type_id": 1,
    "user_id": 1,
    "type": "staff",
    "roles": {
        "1": "admin",
        "2": "editor"
    },
    "first_name": "Test",
    "last_name": "Person",
    "email": "test@test.com"
}

As you can see, now the fields associated with the authentication API are populated. Furthermore, you can search for users using those fields now:

curl -i -X GET --header "Authorization: Bearer dcaf0aa35879e87633280a8fa43034014c4ba803" \
  http://localhost:8000/users?username=adm
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.8
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, X-Token-Expires
Access-Control-Allow-Methods: HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE

{
    "users": [
        {
            "id": 1,
            "username": "admin",
            "active": 1,
            "manage": 1,
            "type_id": 1,
            "user_id": 1,
            "type": "staff",
            "roles": {
                "1": "admin"
            },
            "first_name": "Test",
            "last_name": "Person",
            "email": "test@test.com"
        }
    ]
}

Top