CandidCo Photoset and Treatmentphoto API

api.md

API Requests/Responses

Things that this API allows a client to do:

• get a photoset by its id
• associate a treatmentphoto with a photoset
• get a list of all the photos associated with a photoset
• reorder treatmentphotos in a photoset
• approve or reject a photoset
• remove a treatmentphoto from a photoset
• create/delete crop bounds for a photo

######### potential ways in which this can blow up (will move this somewhere later)

1. "order" values are not unique in HTTP PUT from client
2. "order" values are not continuous over 0..7 (e.g. we're missing "order": 4 or something)
3. invalid value for "approval_status"
4. "approval_status" specified but no "treatment_photo_id" provided
5. "treatment_photo_id" is malformed
6. "treatment_photo_id" is well-formed but semantically invalid (e.g. doesn't exist in database)
7. photoset id in URL doesn't correspond to a photoset in the database
8. OPTIONAL? "treatment_photo_id"/photoset id-combo is invalid

Get a Photoset

Request

HTTP GET /api/v1/photosets/4
Content-type: application/json

Request-body: <empty>

Response

The user has uploaded two images. One has been cropped, the other not.

HTTP 200 OK
Content-type: application/json

{
  "customer_id": 123,
  "treatment_photos": [
    {
      "order": 0,
      "treatment_photo_id": 1,
      "approval_status": "UNREVIEWED",
      "photo_url": "https://s3.whatever.com/teeth.jpg"
    },
    {
      "order": 1,
      "treatment_photo_id": 10,
      "approval_status": "UNREVIEWED",
      "uncropped_photo_url": "https://s3.whatever.com/teeth1.jpg",
      "photo_url": "http://localhost:8000/api/v1/viewImage?url=https%3A%2F%2Fs3.whatever.com%2Fteeth1.jpg&top=10&left=10&right=10&bottom=10",
      "cropBounds" {
        "top": 10,
        "bottom": 10,
        "left": 10,
        "right": 10
      }
    },
    {
      "order": 2
    },
    {
      "order": 3
    },
    {
      "order": 4
    },
    {
      "order": 5
    },
    {
      "order": 6
    },
    {
      "order": 7
    }
  ]
}

Update a Photoset

Request (Reorder photos)

Swap the first and second photos:

HTTP PUT /api/v1/photosets/4
Content-type: application/json

Request-body:

{
  "customer_id": 123,
  "treatment_photos": [
    {
      "order": 0,
      "treatment_photo_id": 1,
      "ops_approval_status": "UNREVIEWED"
    },
    {
      "order": 1,
      "treatment_photo_id": 2,
      "ops_approval_status": "UNREVIEWED"
    },
    {
      "order": 2
    },
    {
      "order": 3
    },
    {
      "order": 4
    },
    {
      "order": 5
    },
    {
      "order": 6
    },
    {
      "order": 7
    }
  ]
}

Response (success)

HTTP 204 No Content

Request-body: <empty>

Request (approve)

Approve the first photo and reject the second:

HTTP PUT /api/v1/photosets/4
Content-type: application/json

Request body:

{
    "customer_id": 123,
    "treatment_photos": [
        {
            "order": 2,
            "ops_approval_status": "APPROVED",
            "treatment_photo_id": 2
        },
        {
            "order": 3,
            "ops_approval_status": "REJECTED",
            "treatment_photo_id": 54
        }
    ]
}

Update Crop Bounds

Request

Set the crop bounds to 10px in from each of the image's edges:

HTTP PUT /api/v1/photosets/4
Content-type: application/json

Request body:

{
    "customer_id": 123,
    "treatment_photos": [
        {
            "order": 2,
            "ops_approval_status": "UNAPPROVED",
            "treatment_photo_id": 2,
            "photo_url": "http://s3.whatever.com/bucket/img.png",
            "crop_bounds": {
              "top": 10,
              "right": 10,
              "left": 10,
              "bottom": 10
            }
        }
    ]
}

Subsequent GET request will contain a photo URL to the cropped asset:

HTTP GET /api/v1/photosets/4
Content-type: application/json

Request body: <empty>

Response body:

{
    "customer_id": 123,
    "treatment_photos": [
        {
            "order": 2,
            "ops_approval_status": "UNAPPROVED",
            "treatment_photo_id": 2,
            "photo_url": "http://s3.whatever.com/bucket/cropped-img.png",
            "uncropped_photo_url": "http://s3.whatever.com/bucket/img.png",
            "crop_bounds": {
              "top": 10,
              "right": 10,
              "left": 10,
              "bottom": 10
            }
        }
    ]
}