HTTP endpoint(s) for Jobs exposing a CRUD RESTful API

[martintoreilly]

Description

HTTP endpoint(s) exposing a RESTful API that supports CRUD (Create, Read, Update, Delete) operations on the applications Job repository

Implementation notes

• Job IDs will be treated as strings for URL parsing. This supports both integer and UUID Job IDs. The underlying Jobs repository should handle conversion from string to the actual type of its ID field.
• For now Job JSON is considered valid if it has an "id" field (see middleware.job.model.py. Once we switch to a database-backed repo, we will very likely want to have stricter validation as we will likely have a stronger binding between code Job model and database Job model.

Job-specific operations

Endpoint: /job/<string:job_id>, handler JobApi

• [x] GET (READ) /job/<job_id>: Retrieve job specification JSON for provided job ID
  • [x] Returns 404 - Not found if no job exists with specified ID
  • [x] Returns 200 - OK with job JSON in message body if job exists with specified ID
• [x] PUT (UPDATE) /job/<job_id>: Update existing job by replacing with provided complete job JSON (Content-Type: application/json)
  • [x] Returns 404 - Not found if no job ID provided in URL
  • [x] Returns 404 - Not found if no job exists with job ID provided in URL
  • [x] Returns 400 - Bad request if request body is empty
  • [x] Returns 409 - Conflict if job IDs in URL and request JSON don't match
  • [x] Returns 400 - Bad request if body is not valid JSON
  • [x] Returns 400 - Bad request if body JSON not valid Job JSON
  • [x] Returns 200 - OK with updated job JSON in message body if job exists with specified ID
• [x] DELETE (DELETE) /job/<job_id>: Delete job specification for provided job ID
  • [x] Returns 404 - Not found if no job exists with specified ID
  • [x] Returns 204 - No contentwith empty message body if job exists with specified ID
• [x] PATCH (PARTIAL UPDATE) /job/<job_id>: Patch specified job using partial Job JSON provided in body (Content-Type: application/merge-patch+json)
  • [x] Returns 404 - Not found if no job ID provided in URL
  • [x] Returns 404 - Not found if no job exists with job ID provided in URL
  • [x] Returns 400 - Bad request if request body is empty
  • [x] Returns 409 - Conflict if job IDs in URL and request JSON don't match
  • [x] Returns 400 - Bad request if body is not valid JSON
  • [x] Returns 400 - Bad request if body JSON not valid partial Job JSON
  • We validate Job JSON resulting from applying patch to see if it is valid. This will always be the case at the moment as we only require presence of ID field and we don't allow this to be changed via PUT or PATCH. Therefore we cannot test this at the moment.
  • [x] Returns 200 - OK with full updated job JSON in message body if job exists with specified ID
  • For simplicity, we are using the JSON merge patch standard described in RFC 7396, which takes a subset of the target JSON structure as input (Content-Type: application/merge-patch+json). We are not using the JSON patch standard described in RFC 6902, which takes explicit edit operations as input (Content-Type: application/json-patch+json). While the explicit edit approach of JSON patch would provide maximum flexibility in the low-level Job API, we don't (yet) need this flexibility and using JSON merge patch means we can use similar validation as we do for the PUT action and don't need to work out how to validate patches (to e.g. ensure we don't allow Job ID to change).
• We are using the json-merge-patch package (source).

Generic operations

Endpoint: /job, handler JobsApi

• [x] POST (CREATE) /job: Creates new job from Job specification JSON (Content-Type: application/json)
  • [x] Returns 400 - Bad request if request body body is empty
  • [x] Returns 409 - Conflict if job with same ID already exists
  • [x] Returns 400 - Bad request if body is not valid JSON
  • [x] Returns 400 - Bad request if body JSON not valid Job JSON
  • [x] Returns 200 - OK with job JSON in message body if no job exists with specified ID
• [x] GET (LIST) /job: Lists all existing jobs
  • [x] Returns 200 - OK with JSON array of object representations for existing jobs in message body (i.e.. If no jobs exist then an empty list is returned).
  • Job object representation is {"id": <job-id>, "uri": "/job/<job_id>"}
  • We should expand the representation returned by the LIST endpoint to include useful Job properties for users to distinguish / filter / sort jobs in a list (e.g. name, case, status)

Note: To expose a unified endpoint URL structure, we've used /job/ as the root, with the presence or absence of the <job_id> URL fragment determining which handler to route to.

[martintoreilly]

See PR #12 for implementation of POST (CREATE), GET (READ), GET (LIST), PUT (Replacement UPDATE), DELETE (DELETE).

[martintoreilly]

See PR #16 for PATCH (Partial update) using JSON merge patch approach.

[martintoreilly]

Closing following merge of PR #16