Validate content type is yaml for manifest diff endpoint

- Also update documentation with some extra definitions and a table of
possible return values

[#173478913](https://www.pivotaltracker.com/story/show/173478913)

Co-authored-by: Nick Webb <nwebb@pivotal.io>
Co-authored-by: Reid Mitchell <rmitchell@pivotal.io>

Author: nickjameswebb

app/controllers/v3/space_manifests_controller.rb

@@ -8,7 +8,7 @@
 class SpaceManifestsController < ApplicationController
   wrap_parameters :body, format: [:yaml]
 
-  before_action :validate_content_type!, only: :apply_manifest
+  before_action :validate_content_type!
 
   def apply_manifest
     space = Space.find(guid: hashed_params[:guid])
@@ -103,7 +103,7 @@ def compound_error!(error_messages)
 
   def validate_content_type!
     if !request_content_type_is_yaml?
-      logger.error("Context-type isn't yaml: #{request.content_type}")
+      logger.error("Content-type isn't yaml: #{request.content_type}")
       invalid_request!('Content-Type must be yaml')
     end
   end

docs/v3/source/includes/resources/manifests/_create_diff.md

@@ -7,6 +7,7 @@ Example Request
 ```shell
 curl "https://api.example.org/v3/spaces/[guid]/manifest_diff" \
   -X POST \
+  -H "Content-Type: application/x-yaml" \
   -H "Authorization: bearer [token]" \
   -d @/path/to/manifest.yml
 ```
@@ -41,12 +42,28 @@ Content-Type: application/json
 }
 ```
 
-Create a manifest diff for apps in the provided manifest and their underlying processes. Currently manifest_diff only supports version 1 manifests.
+This endpoint returns a JSON representation of the difference between the
+provided manifest and the current state of a space.
 
-Manifests require the `applications` field.
+Currently, this endpoint can only diff [version 1](#the-manifest-schema) manifests.
+
+##### The diff object
+
+The diff object format is inspired by the [JSON Patch
+specification](https://tools.ietf.org/html/rfc6902).
+
+Name           | Type | Description
+-------------- | ---- | -----------
+**op** | _string_ | Type of change; valid values are `add`, `remove`, `replace`
+**path** | _string_ | Path to changing manifest field
+**was** | _any_ | For `remove` and `replace` operations, the previous value;
+otherwise key is omitted
+**value** | _any_ | For `add` and `replace` operations, the new value; otherwise
+key is omitted
 
 #### Definition
-`GET /v3/spaces/:guid/manifest_diff`
+
+`POST /v3/spaces/:guid/manifest_diff`
 
 #### Permitted Roles
  |

spec/request/space_manifests_spec.rb

@@ -635,7 +635,53 @@
           expect(parsed_response['errors'].first['detail']).to eq('Unsupported manifest schema version. Currently supported versions: [1].')
         end
       end
+
+      context 'the content-type is omitted' do
+        let(:yml_manifest) do
+          {
+            'applications' => [
+              {
+                'name' => 'new-app',
+              },
+            ]
+          }.to_yaml
+        end
+
+        it 'returns an appropriate error' do
+          headers = yml_headers(user_header)
+          headers.delete('CONTENT_TYPE')
+          post "/v3/spaces/#{space.guid}/manifest_diff", yml_manifest, headers
+          parsed_response = MultiJson.load(last_response.body)
+
+          expect(last_response).to have_status_code(400)
+          expect(parsed_response['errors'].first['detail']).to eq('The request is invalid')
+        end
+      end
+
+      context 'the content-type is not yaml' do
+        let(:yml_manifest) do
+          {
+            'applications' => [
+              {
+                'name' => 'new-app',
+              },
+            ]
+          }.to_yaml
+        end
+
+        it 'returns an appropriate error' do
+          headers = yml_headers(user_header)
+          headers['CONTENT_TYPE'] = 'bogus'
+
+          post "/v3/spaces/#{space.guid}/manifest_diff", yml_manifest, headers
+          parsed_response = MultiJson.load(last_response.body)
+
+          expect(last_response).to have_status_code(400)
+          expect(parsed_response['errors'].first['detail']).to eq('The request is invalid')
+        end
+      end
     end
+
     context 'the space does not exist' do
       let(:yml_manifest) do
         {