Home

Cougar Framework Tutorial

This tutorial will introduce you to the Cougar Framework as you write a REST API for a simple database-driven web application. The application contains information about all 50 U. S. states and allows users to indicate which states they have visited. Users and visitors can get information about each state and see how many users have visited a particular state. Authenticated users will be able to see information on the individual users that have visited the state. The application includes full user management, administrative controls and full security.

The application is documented and purposely verbose to increase its educational value. It is written in about 1,000 lines of code and contains full unit tests to demonstrate testing patterns.

Disclaimers

As mentioned in the previous paragraph, the tutorial is designed to introduce features and patterns used in the Cougar Framework. It is not meant to be a contest to reduce code base, write the fastest application nor be the prettiest application out there. If there are things you don't like, feel free to discuss and provide insights on how things can be improved.

Additionally, the application does not have a pretty GUI. If you want to write a nice GUI in Angular, I welcome the contribution.

Application Requirements

The application must expose all functionality via REST web services and must be secure.

State Information

The application will need to have information on all 50 U.S. states. The information for each state will include:

• Name
• Two-letter postal code
• Capital city
• Largest city
• Population
• Number of counties
• Date when the state joined the union

All of this information must be queryable. The user must be able to get a list of states that match any given criteria. For example:

• States that have a population above or below a given value
• States that start with the word "North"
• States that joined the union after or before a given date, or between or outside a given date range

User Management

The application must allow new users to register. The application should use the user's email address as the username and collect the user's name. Passwords must be hashed before being stored in the database.

Once registered, users can mark any of the 50 states they have visited. Users must be allowed to unmark a state they had previously marked as visited. Users must be able to get a list of states they have marked as visited. Users must not be allowed to mark or unmark states for other users.

The application must allow administrative users. Administrative users are able to perform all functions for any other user. They are also able to update a state's population and largest city, but not change any other state information.

Security requirements

The application must be publicly accessible but not expose user information to unauthenticated users. Thus, the application must behave differently based on whether the user has authenticated and whether the user has administrative rights to the application.

Unauthenticated users (public) are allowed to perform the following functions:

• Get a list of all 50 U.S. states
• Query state information
• See how many users have visited the state; user information must not be disclosed
• Register as a user

Authenticated users are allowed to perform the following functions in addition to the public functionality:

• Update their user information
• Mark and unmark any state as visited
• View the list of users that have visited a particular state; the list should include the user's name and email address
• Get a list of states that a particular user has visited

Administrative users are allowed to perform the following additional functionality beyond the authenticated user's functionality:

• List users
• Perform any of the authenticated user's functionality in behalf of the user
• Update the population and change the largest city on any state

With that information, you are now ready to get started.