Public Repository

Last pushed: 9 months ago
Short Description
Oak RESTful API written in Ruby on Rails
Full Description


A RESTful API that Oak uses to manage data related to courses, comments, ratings, users, etc. The API returns all data in JSON format and uses HTTP verbs and status codes to communicate intent. This API is built on Ruby on Rails and makes use of Devise and devise_auth_token for user authentication. JSON templates are also generated using Jbuilder.


This project makes use of Docker for the development environment to maintain consistency.


Clone the repository to your computer.

Make sure Docker is running. Open a console in the root of the project directory and enter:

docker-compose build

This will download and build the required images to run the API. WARNING: This step takes quite a while depending on your internet connection, so feel free to take this time to grab a coffee or read through the rest of this document. If you make a change to the Dockerfiles or docker-compose.yml, you will have to run this command again to rebuild the image, but depending on your changes, subsequent builds will be much faster due to caching. At this point you could try to run docker-compose up, which starts all the required services, but you will receive a bunch of errors because the database has not been generated yet.

Generating the Database

To generate the database for development and testing environments, run this commands in your console:

docker-compose run web bundle exec rails db:setup

This will generate development and test databases, as well as run migrations. You only have to do this once.

Populating the Database with Courses

To populate the database with courses from Cobalt datasets, run:

docker-compose run web bundle exec rake app:update_courses

This may take some time, but when it completes, your development database will be populated with courses from the most recent academic year.

Creating a User

You may also want to create a user so that you can get an authentication token to test different routes. To do this, you will need to run a rails console:

docker-compose run web bundle exec rails c

You will need to create a new user with email and password using the create method on the User model:

User.create(name: 'John Smith', email: '', password: 'valid_password');

You can exit out of the Rails console by simply typing exit.


To start the required containers for the first time:

docker-compose up

This will start a server on http://localhost:3000 under the development environment. You can interact with the API using curl if you prefer using the command line. However, it is recommended that you make use of a GUI application such as Postman or Insomnia. You will need to include the HTTP header Accept: application/vnd.oak.v1 in order for any requests to work.

To run tests in a running container:

docker-compose exec web bundle exec rails test

To stop the containers:

docker-compose stop

To start up a container:

docker-compose start

NOTE: This command is different from docker-compose up because it only starts existing containers, whereas the up command creates AND starts new containers

To list running containers:

docker-compose ps

To stop and remove the containers:

docker-compose down

API Endpoints

The API exposes the following RESTful endpoints:

HTTP Verb Endpoint Functionality
POST /auth Create account
GET /auth Show account
PUT /auth Update account
DELETE /auth Delete account
POST /auth/sign_in Login
DELETE /auth/sign_out Logout
GET /users List all users
GET /users/:id Show a user
GET /courses List all courses
GET /courses/:id Show a course
GET /courses/:id/comments List all course comments
POST /courses/:id/comments Add a course comment
GET /comments/:id Show a course comment
PUT /comments/:id Update a course comment
DELETE /comments/:id Delete a course comment
POST /comments/:id/reply Reply to a comment
GET /courses/:id/ratings List all course ratings
POST /courses/:id/ratings Add a course rating
GET /ratings/:id Show a course rating
PUT /ratings/:id Update a course rating


Please open an issue for support.


Please contribute using by creating a separate branch from development as base or forking the repository. Add your commits and then open a pull request.


This project is licensed under the MIT License - see the LICENSE file for details.

Docker Pull Command