Update README to include docker, start check script

Author: cwinters

.gitignore

@@ -0,0 +1 @@
+exercise/venv/*

README.md

@@ -23,7 +23,121 @@ Below are two sections:
 
 # Instructions
 
-There is a problem. You need to solve it.
+## Problem
+
+We're starting a new application and we need to store students! We'd like to be
+able to do the following with the students:
+
+* Create a student
+* Retrieve a particular student by unique identifier
+* Search students in the system
+
+__0.__ Format -- the application should accept and produce JSON.
+
+__1.__ Data -- the student record has the following fields:
+
+* Either an `email` or a `username` must be non-blank, and whichever (or both)
+  are defined they must be unique for that field.
+* A `first_name` and `last_name`; the `last_name` is required to be non-blank.
+* A `display_name`, which if not defined at creation should be the first name
+  and last names joined with a space.
+* The `created_at` datetime when the student was added to the system, which
+  should be assigned by the system when the student is created.
+* The `started_at` of the student started at an institution; if not specified
+  it should be the date the student was added to the system.
+
+__2.__ Search -- the students may be searched by the following fields:
+
+* `name` (which is a partial match against any of the first name, last name, or
+  display name)
+* `username` (partial match)
+* `email` (partial match)
+* `started_after` (date formatted `YYYY-MM-DD` that will return students
+  who started on or after a particular date)
+
+If multiple fields provided any returned records must match all of them, so
+treat them as an `AND`.
+
+__3.__ Routes -- the routes you should use are:
+
+* Create a student: `POST /students`
+* Search students: `GET /students`
+* Retrieve a student: `GET /students/{identifier}`
+* Health check: `GET /` should return a successful HTTP status
+
+## Languages and Environment
+
+__1.__ You may use any of the following languages to solve this problem:
+
+* Python
+* JavaScript
+* Ruby
+* Go
+* Java
+
+__2.__ If you use external libraries you should use standard dependency
+management tools to declare them -- for example, `requirements.txt` for Python
+projects, `Gemfile` for Ruby projects, etc.
+
+__3.__ If you use a relational database please use Postgres.
+
+__4.__ Using Docker (with a `Dockerfile`) is also just fine. We use Docker for
+development, testing, and production here, but you're not required to know it
+when you start.
+
+__5.__ Unit tests are strongly encouraged.
+
+__6.__ Please include with your solution instructions on what we need to do to
+run it.
+
+## Checking your work
+
+There is a directory in this repo `exercise/` with a script that you can use to
+exercise your solution. You can run it in two ways:
+
+__1.__ Run without Docker
+
+It requires python to be installed and a particular module to be installed.
+[Virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/) is a
+great way to manage and isolate dependencies, and you can do so with the
+exercise like this, assuming you're using some sort of Unix-y command-line:
+
+```
+$ cd exercise
+$ virtualenv venv
+$ source venv/bin/activate
+$ pip install -r requirements.txt
+```
+
+If you don't have `virtualenv` you can install with
+
+```
+$ sudo pip install virtualenv
+```
+
+Once you've got the environment setup you can run it like this:
+
+```
+$ python check.py http://myhost:8888
+```
+
+where `http://myhost:8888` is the URL where your solution is running.
+
+It uses the same data every time to run its checks so you'll need to have a
+clean datastore before you run it.
+
+__2.__ Run with Docker
+
+If you already have Docker installed you can build a container and
+point it at your solution. Note that mapping the host on which your solution is
+running (`myhost`, below) to the host known by the docker container may be
+tricky.
+
+```
+$ cd exercise
+$ docker build -t turnitin-check .
+$ docker run --rm turnitin-check http://myhost:8888
+```
 
 # Logistics
 
@@ -34,7 +148,7 @@ a whole weekend to work on it.
 __2.__ You will need to use git for this exercise. To get these instructions
 and a repo with test scripts do the following:
 
-A: (Create a bitbucket account)[https://bitbucket.org/account/signup/] if you
+A: [Create a bitbucket account](https://bitbucket.org/account/signup/) if you
 don't already have one. For the examples below we assume a user `pusheen`.
 
 B: Clone our repository:
@@ -51,7 +165,7 @@ __3.__ Once you are done you can put your solution in your own repository by
 adding it as a remote and pushing to it.
 
 A: Create a new repo via the bitbucket UI, let's assume you call it
-`backend-coding-exercise` to mirror ours.
+`backend-code-exercise` to mirror ours.
 
 B: Please make the repository *private*, we'd like to make sure that every
 candidate's work is his or her own.

exercise/Dockerfile

@@ -0,0 +1,9 @@
+FROM       python:alpine
+
+RUN        mkdir /app
+WORKDIR    /app
+ADD        requirements.txt /app/
+RUN        pip install -r requirements.txt
+ADD        . /app
+
+ENTRYPOINT ["python", "check.py"]

exercise/check.py

@@ -0,0 +1,71 @@
+import sys
+import unittest
+
+import requests
+
+BASE = None
+
+
+class VerifyStudents(unittest.TestCase):
+    def get(self, query_args={}):
+        return requests.get(self.url(), params=query_args)
+
+    def post(self, body_dict={}):
+        return requests.post(self.url(), json=body_dict)
+
+    def url(self):
+        return BASE + self.path()
+
+    def assert_post_not_ok(self, body_dict, msg):
+        self.assert_response_not_between(self.post(body_dict), 200, 300, msg)
+
+    def assert_response_between(self, response, low, high, msg):
+        status = response.status_code
+        if status not in range(low, high):
+            self.fail(msg + ', expected status between {} and {}, got {}'.format(low, high, status))
+
+    def assert_response_not_between(self, response, low, high, msg):
+        status = response.status_code
+        if status in range(low, high):
+            self.fail(msg + ', expected status NOT between {} and {}, got {}'.format(low, high, status))
+
+
+class VerifyCreate(VerifyStudents):
+    def path(self):
+        return '/students'
+
+    def valid_student(self, updates={}):
+        student = {
+            'email': 'pusheen@example.com',
+            'first_name': 'Push',
+            'last_name': 'Een',
+        }
+        student.update(updates)
+        return student
+
+    def test_fail_missing_last_name(self):
+        doc = self.valid_student({'last_name': None})
+        self.assert_post_not_ok(doc, 'Expected error with no last name')
+
+
+if __name__ == '__main__':
+    if len(sys.argv) == 1:
+        print("Usage: python {} url-of-solution".format(sys.argv[0]))
+        sys.exit(1)
+
+    BASE = sys.argv[1].rstrip('/')
+
+    # lop this off so unittest doesn't try to do something with it
+    del(sys.argv[1])
+
+    try:
+        response = requests.get(BASE + '/')
+        if response.status_code >= 400:
+            print("FAIL: Health check got bad status ({}), not continuing".format(response.status_code))
+            sys.exit(1)
+    except requests.RequestException as e:
+        print("FAIL: Caught exception with health check -- {}".format(e))
+        sys.exit(1)
+
+    print("OK: Health check")
+    unittest.main(verbosity=2)

exercise/requirements.txt

@@ -0,0 +1,2 @@
+requests==2.12.0
+