PT-1036 - Updated services_documentation to include support for error…

… messages and added error messages to active custom services resources.

modules/custom/petitions_api/api_petitions/api_petitions.module

@@ -347,7 +347,8 @@ function _api_petitions_resource_retrieve($petition_id, $mock) {
     $developer_message = t("Class could not be instantiated.");
     $user_message = t("The resource that you requested is temporarily unavailable.");
     $error_code = 83;
-    $more_info = t('See issue #!code on github: https://github.com/whitehouse/petitions/issues/!code', array('!code' => $error_code));
+    $more_info = t('See the documentation: !url/developers#petitions-retrieve-error-599', array('!url' => $website_url));
+    watchdog('api_petitions', $e->getMessage());
     return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
   }
 
@@ -357,8 +358,8 @@ function _api_petitions_resource_retrieve($petition_id, $mock) {
     $developer_message = t("Petition @petition_id not found.", array('@petition_id' => $petition_id));
     $user_message = t("The petition that you requested does not exist.", array('@petition_id' => $petition_id));
     $error_code = 84;
-    $more_info = t('See issue #!code on github: https://github.com/whitehouse/petitions/issues/!code', array('!code' => $error_code));
-    return api_errors_throw_error($status_code, $developer_message, $user_message);
+    $more_info = t('See the documentation: !url/developers#petitions-retrieve-error-404', array('!url' => $website_url));
+    return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
   }
 
   $response_params = array(
@@ -501,6 +502,10 @@ function _api_petitions_resource_index($is_public, $is_signable, $created_before
  * Callback for Services petitions signatures relationship method.
  */
 function _api_petitions_load_signatures($petition_id, $city, $state, $zipcode, $country, $created_before, $created_after, $created_at, $limit, $offset, $mock) {
+  global $base_url;
+
+  $website_url = variable_get('petitions_data_petitions_website_url', $base_url);
+
   // Return mock response.
   if ($mock) {
     $response = json_decode(_api_petitions_mock_response('load_signatures'));
@@ -538,7 +543,7 @@ function _api_petitions_load_signatures($petition_id, $city, $state, $zipcode, $
     $developer_message = t("Class could not be instantiated.");
     $user_message = t("The resource that you requested is temporarily unavailable.");
     $error_code = 83;
-    $more_info = t('See issue #!code on github: https://github.com/whitehouse/petitions/issues/!code', array('!code' => $error_code));
+    $more_info = t('See the documentation: !url/developers#petitions-signatures-error-599', array('!url' => $website_url));
     watchdog('api_petitions', $e->getMessage());
     return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
   }
@@ -556,6 +561,7 @@ function _api_petitions_retrieve_doc() {
     '#request_url' => url(variable_get('petitions_data_petitions_api_url', '') . '/v1/petitions/50a3fd762f2c88cd65000015.json', array('absolute' => TRUE)),
     '#response' => _api_petitions_mock_response('retrieve'),
     '#example_implementations_bundles' => _api_petitions_retrieve_doc_example_implementations_bundles(),
+    '#errors' => _api_petitions_retrieve_doc_errors(),
   );
 
   return $element;
@@ -592,6 +598,26 @@ function _api_petitions_retrieve_doc_example_implementations() {
   return $example_implementations;
 }
 
+/**
+ * Documentation callback for errors related to the retrieve method.
+ */
+function _api_petitions_retrieve_doc_errors() {
+  $errors = array(
+    '404' => array(
+      '#question' => t("What happens when I pass an invalid petition ID with my request?"),
+      '#description' => t("I am building a web application that will communicate via the read API. If I pass an invalid petition ID with my request, will I get a response?"),
+      '#response' => _api_petitions_mock_response('retrieve404'),
+    ),
+    '599' => array (
+      '#question' => t("What happens when I make a request and the application fails?"),
+      '#description' => t("I am building a web application that will communicate via the API. If the service fails to respond due to internal errors, will I get a response?"),
+      '#response' => _api_petitions_mock_response('retrieve599'),
+    ),
+  );
+
+  return $errors;
+}
+
 /**
  * Documentation callback for index method.
  */
@@ -605,11 +631,26 @@ function _api_petitions_index_doc() {
 Limits: 10 requests per second. Developers who need historic data on all public petitions should consider using our bulk data download, described above.'),
     '#request_url' => variable_get('petitions_data_petitions_api_url', '') . '/v1/petitions.json?limit=3&offset=0&createdBefore=1352924535',
     '#response' => _api_petitions_mock_response('index'),
+    '#errors' => _api_petitions_index_doc_errors(),
   );
 
   return $element;
 }
 
+/**
+ * Documentation callback for errors related to the index method.
+ */
+function _api_petitions_index_doc_errors() {
+  // @todo Have all possible errors been captured?.
+  $errors = array(
+    '599' => array (
+      '#response' => _api_petitions_mock_response('index599'),
+    ),
+  );
+
+  return $errors;
+}
+
 /**
  * Documentation callback for relationship method.
  */
@@ -621,12 +662,28 @@ function _api_petitions_load_signatures_doc() {
     '#description' => t('Display signatures attached to a petition. Unsupported non-Latin characters are replaced with an "x".'),
     '#request_url' => url(variable_get('petitions_data_petitions_api_url', '') . '/v1/petitions/50a3fd762f2c88cd65000015/signatures.json?limit=16&offset=0', array('absolute' => TRUE)),
     '#response' => _api_petitions_mock_response('load_signatures'),
+    '#errors' => _api_petitions_load_signatures_doc_errors(),
     '#verb' => 'GET',
   );
 
   return $element;
 }
 
+/**
+ * Documentation callback for errors related to the signatures relationship.
+ */
+function _api_petitions_load_signatures_doc_errors() {
+  $errors = array(
+    '599' => array (
+      '#question' => t("What happens when I make a request and the application fails?"),
+      '#description' => t("I am building a web application that will communicate via the API. If the service fails to respond due to internal errors, will I get a response?"),
+      '#response' => _api_petitions_mock_response('load_signatures599')
+    ),
+  );
+
+  return $errors;
+}
+
 /**
  * Returns a mock response for petitions methods.
  */
@@ -636,14 +693,30 @@ function _api_petitions_mock_response($method) {
       $file = 'api_petitions_index.response.json';
       break;
 
+    case 'index599':
+      $file = 'api_petitions_index.response599.json';
+      break;
+
     case 'retrieve':
       $file = 'api_petitions_retrieve.response.json';
       break;
 
+    case 'retrieve404':
+      $file = 'api_petitions_retrieve.response404.json';
+      break;
+
+    case 'retrieve599':
+      $file = 'api_petitions_retrieve.response599.json';
+      break;
+
     case 'load_signatures':
       $file = 'api_petitions_load_signatures.response.json';
       break;
 
+    case 'load_signatures599':
+      $file = 'api_petitions_load_signatures.response599.json';
+      break;
+
   }
   $response = file_get_contents(drupal_get_path('module', 'api_petitions') . '/example_responses/' . $file);
   return $response;

modules/custom/petitions_api/api_petitions/example_responses/api_petitions_index.response599.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "599",
+      "developerMessage:": "Sorry. Something went wrong. We're not sure what. And we're not sure 599 is an accurate status code for your error. Please file a ticket in the issue queue to help us understand what caused this error: https://github.com/whitehouse/petitions/issues?state=open",
+      "userMessage": "",
+      "errorCode": "",
+      "moreInfo": ""
+    }
+  }
+}

modules/custom/petitions_api/api_petitions/example_responses/api_petitions_load_signatures.response599.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "599",
+      "developerMessage:": "Class could not be instantiated.",
+      "userMessage": "The resource that you requested is temporarily unavailable.",
+      "errorCode": "83",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#petitions-signatures-error-599"
+    }
+  }
+}

modules/custom/petitions_api/api_petitions/example_responses/api_petitions_retrieve.response404.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "404",
+      "developerMessage:": "Petition {petition_id} not found.",
+      "userMessage": "The petition that you requested does not exist.",
+      "errorCode": "84",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#petitions-retrieve-error-404"
+    }
+  }
+}

modules/custom/petitions_api/api_petitions/example_responses/api_petitions_retrieve.response599.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "599",
+      "developerMessage:": "Class could not be instantiated.",
+      "userMessage": "The resource that you requested is temporarily unavailable.",
+      "errorCode": "83",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#petitions-retrieve-error-599"
+    }
+  }
+}

modules/custom/petitions_api/api_signatures/api_signatures.inc

@@ -17,6 +17,9 @@
  *   A REST response array as formatted by api_services_responses_format().
  */
 function _api_signatures_resource_create($api_key, array $signature) {
+  global $base_url;
+
+  $website_url = variable_get('petitions_data_petitions_website_url', $base_url);
 
   // Verbose logging, if debugging is enabled.
   if ($debug = variable_get('signatures_queue_enable_debugging', FALSE)) {
@@ -33,7 +36,9 @@ function _api_signatures_resource_create($api_key, array $signature) {
     $status_code = 401;
     $developer_message = t("Invalid key.");
     $user_message = t("The key provided is not valid.");
-    return api_errors_throw_error($status_code, $developer_message, $user_message);
+    $more_info = t('See the documentation: !url/developers#signatures-create-error-401', array('!url' => $website_url));
+    $error_code = 85;
+    return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
   }
 
   // Add the API Key to the signature.
@@ -45,41 +50,45 @@ function _api_signatures_resource_create($api_key, array $signature) {
 
   // Deliver response.
   switch ($status_code) {
+    // 200.
     case SIGNATURES_QUEUE_STATUS_OK:
       // Return successsful, generic response.
       return api_services_responses_format();
 
+    // 400.
     case SIGNATURES_QUEUE_STATUS_BAD_REQUEST:
       $developer_message = $user_message = t('Missing required fields. These fields are required: signature_source_api_key, petition_id, email, first_name, last_name.');
-      $more_info = 'https://github.com/WhiteHouse/petitions/issues/75';
+      $more_info = t('See the documentation: !url/developers#signatures-create-error-400', array('!url' => $website_url));
       $error_code = 75;
       return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
 
+    // 403.
     case SIGNATURES_QUEUE_STATUS_FORBIDDEN:
-      global $base_url;
       $developer_message = t("Petition @petition_id cannot accept more signatures. (If you believe this petition was not open for a full 30 days, it's possible that it was flagged and removed for violation of terms of service.)", array(
         '@petition_id' => $signature['petition_id'],
       ));
       $user_message = t('This petition cannot accept more signatures. You can open a new petition on this issue here: @url.', array(
         '@url' => "{$base_url}/",
       ));
-      $more_info = 'https://github.com/WhiteHouse/petitions/issues/74';
+      $more_info = t('See the documentation: !url/developers#signatures-create-error-403', array('!url' => $website_url));
       $error_code = 74;
       return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
 
+    // 404.
     case SIGNATURES_QUEUE_STATUS_NOT_FOUND:
       $developer_message = t("No such petition @petition_id", array(
         '@petition_id' => $signature['petition_id'],
       ));
       $user_message = t("The petition you are trying to sign doesn't exist.");
-      $more_info = 'https://github.com/WhiteHouse/petitions/issues/76';
+      $more_info = t('See the documentation: !url/developers#signatures-create-error-404', array('!url' => $website_url));
       $error_code = 76;
       return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
 
+    // 500.
     case SIGNATURES_QUEUE_STATUS_SERVER_ERROR:
       $developer_message = t('Sorry. Service is not available right now.');
       $user_message = t('Sorry. We are unable to process your signature right now.');
-      $more_info = 'https://github.com/WhiteHouse/petitions/issues/73';
+      $more_info = t('See the documentation: !url/developers#signatures-create-error-500', array('!url' => $website_url));
       $error_code = 73;
       return api_errors_throw_error($status_code, $developer_message, $user_message, $more_info, $error_code);
   }

modules/custom/petitions_api/api_signatures/api_signatures.module

@@ -59,8 +59,49 @@ function _api_signatures_create_doc() {
     '#request_url' => url(variable_get('petitions_data_petitions_api_url', '') . '/v1/signatures.json?api_key=asY1k9uCQY7Hg8MCBaa', array('absolute' => TRUE)),
     '#request_data' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.request.json'),
     '#response' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.response.json'),
+    '#errors' => _api_signatures_create_doc_errors(),
     '#auth' => TRUE,
   );
 
   return $element;
 }
+
+/**
+ * Documentation callback for errors related to the create method.
+ */
+function _api_signatures_create_doc_errors() {
+  global $base_url;
+  $errors = array(
+    // 400
+    SIGNATURES_QUEUE_STATUS_BAD_REQUEST => array(
+      '#question' => t("What happens if my submission does not include all the required fields?"),
+      '#description' => t("I am building a web application that will post petition signatures via the write API. I can definitely foresee a scenario where all of the required fields were not gathered. If I am trying to post a signature via the API at http://api.whitehouse.gov/v1/signatures that does not contain all of the required fields, will I get an error response?"),
+      '#response' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.response400.json'),
+    ),
+    '401' => array(
+      '#question' => t("What happens when I pass an invalid API key with my request?"),
+      '#description' => t("I am building a web application that will submit signatures via the write API and confirm that signatures have been validated via the validations resource. If I pass an invalid API key with my request, will I get a response?"),
+      '#response' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.response401.json'),
+    ),
+    // 403.
+    SIGNATURES_QUEUE_STATUS_FORBIDDEN => array(
+      '#question' => t("What happens when I try to sign a petition that is closed?"),
+      '#description' => t("I am building a web application that will post petition signatures via the write API. If I am trying to post a signature via the API at http://api.whitehouse.gov/v1/signatures to a petition that is more then 30 days old and has since been closed, will I get a response? If so, is there a different response if the petition was closed prior to the 30 days?"),
+      '#response' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.response403.json'),
+    ),
+    // 404.
+    SIGNATURES_QUEUE_STATUS_NOT_FOUND => array(
+      '#question' => t("What happens when I try to sign a petition that doesn't exist?"),
+      '#description' => t("I am building a web application that will post petition signatures via the write API. If I am trying to post a signature via the API at http://api.whitehouse.gov/v1/signatures for a petition that does not actually exist, will I get an error response?"),
+      '#response' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.response404.json'),
+    ),
+    // 500.
+    SIGNATURES_QUEUE_STATUS_SERVER_ERROR => array(
+      '#question' => t("What happens when the API service is not available?"),
+      '#description' => t("I am building a web application that will post petition signatures via the write API. If I am trying to post a signature via the API at http://api.whitehouse.gov/v1/signatures and the service is down, will I get a response?"),
+      '#response' => file_get_contents(__DIR__ . '/examples/' . 'api_signatures_create.response500.json'),
+    ),
+  );
+
+  return $errors;
+}

modules/custom/petitions_api/api_signatures/examples/api_signatures_create.response400.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "400",
+      "developerMessage:": "Missing required fields. These fields are required: signature_source_api_key, petition_id, email, first_name, last_name.",
+      "userMessage": "Missing required fields. These fields are required: signature_source_api_key, petition_id, email, first_name, last_name.",
+      "errorCode": "75",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#signatures-create-error-400"
+    }
+  }
+}

modules/custom/petitions_api/api_signatures/examples/api_signatures_create.response401.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "401",
+      "developerMessage:": "Invalid key.",
+      "userMessage": "The key provided is not valid.",
+      "errorCode": "85",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#signatures-create-error-401"
+    }
+  }
+}

modules/custom/petitions_api/api_signatures/examples/api_signatures_create.response403.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "403",
+      "developerMessage:": "Petition {petition_id} cannot accept more signatures. (If you believe this petition was not open for a full 30 days, it's possible that it was flagged and removed for violation of terms of service.)",
+      "userMessage": "This petition cannot accept more signatures. You can open a new petition on this issue here: https://edit.dev8.petitions.whitehouse.gov/.",
+      "errorCode": "74",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#signatures-create-error-403"
+    }
+  }
+}

modules/custom/petitions_api/api_signatures/examples/api_signatures_create.response404.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "responseInfo": {
+      "status": "404",
+      "developerMessage:": "No such petition {petition_id}.",
+      "userMessage": "The petition you are trying to sign doesn't exist.",
+      "errorCode": "76",
+      "moreInfo": "See the documentation: https://petitions.whitehouse.gov/developers#signatures-create-error-404"
+    }
+  }
+}