[Summary view] [Print] [Text view]

   1  /**
   2   * @output wp-includes/js/api-request.js
   3   */
   4  
   5  /**
   6   * Thin jQuery.ajax wrapper for WP REST API requests.
   7   *
   8   * Currently only applies to requests that do not use the `wp-api.js` Backbone
   9   * client library, though this may change.  Serves several purposes:
  10   *
  11   * - Allows overriding these requests as needed by customized WP installations.
  12   * - Sends the REST API nonce as a request header.
  13   * - Allows specifying only an endpoint namespace/path instead of a full URL.
  14   *
  15   * @since 4.9.0
  16   * @since 5.6.0 Added overriding of the "PUT" and "DELETE" methods with "POST".
  17   *              Added an "application/json" Accept header to all requests.
  18   *
  19   * @param {JQueryStatic} $ The jQuery object.
  20   */
  21  ( function( $ ) {
  22      var wpApiSettings = window.wpApiSettings;
  23  
  24      /**
  25       * Makes an API request.
  26       *
  27       * @param {Object} options                 The options for the API request.
  28       * @param {string} [options.url]           The full URL for the request.
  29       * @param {string} [options.path]          The API path (e.g., 'wp/v2/posts'). Used if url is not provided.
  30       * @param {string} [options.namespace]     The API namespace (e.g., 'wp/v2'). Used with endpoint to build path.
  31       * @param {string} [options.endpoint]      The API endpoint (e.g., 'posts'). Used with namespace to build path.
  32       * @param {string} [options.method]        The HTTP method (GET, POST, PUT, DELETE, etc.).
  33       * @param {Object} [options.data]          The request data to send.
  34       * @param {string} [options.data._wpnonce] Nonce for security.
  35       * @param {Object} [options.headers]       Custom headers to include in the request.
  36       * @return {JQueryXHR} The jQuery XHR object.
  37       */
  38  	function apiRequest( options ) {
  39          options = apiRequest.buildAjaxOptions( options );
  40          return apiRequest.transport( options );
  41      }
  42  
  43      /**
  44       * Builds the options for the jQuery.ajax request.
  45       *
  46       * @param {Object} options             The options for the API request.
  47       * @param {string} [options.url]       The full URL for the request.
  48       * @param {string} [options.path]      The API path (e.g., 'wp/v2/posts'). Used if url is not provided.
  49       * @param {string} [options.namespace] The API namespace (e.g., 'wp/v2'). Used with endpoint to build path.
  50       * @param {string} [options.endpoint]  The API endpoint (e.g., 'posts'). Used with namespace to build path.
  51       * @param {string} [options.method]    The HTTP method (GET, POST, PUT, DELETE, etc.).
  52       * @param {Object} [options.data]      The request data to send.
  53       * @param {Object} [options.headers]   Custom headers to include in the request.
  54       * @return {Object} The options for the jQuery.ajax request.
  55       */
  56      apiRequest.buildAjaxOptions = function( options ) {
  57          var url = options.url;
  58          var path = options.path;
  59          var method = options.method;
  60          var namespaceTrimmed, endpointTrimmed, apiRoot;
  61          var headers, addNonceHeader, addAcceptHeader, headerName;
  62  
  63          if (
  64              typeof options.namespace === 'string' &&
  65              typeof options.endpoint === 'string'
  66          ) {
  67              namespaceTrimmed = options.namespace.replace( /^\/|\/$/g, '' );
  68              endpointTrimmed = options.endpoint.replace( /^\//, '' );
  69              if ( endpointTrimmed ) {
  70                  path = namespaceTrimmed + '/' + endpointTrimmed;
  71              } else {
  72                  path = namespaceTrimmed;
  73              }
  74          }
  75          if ( typeof path === 'string' ) {
  76              apiRoot = wpApiSettings.root;
  77              path = path.replace( /^\//, '' );
  78  
  79              // API root may already include query parameter prefix
  80              // if site is configured to use plain permalinks.
  81              if ( 'string' === typeof apiRoot && -1 !== apiRoot.indexOf( '?' ) ) {
  82                  path = path.replace( '?', '&' );
  83              }
  84  
  85              url = apiRoot + path;
  86          }
  87  
  88          // If ?_wpnonce=... is present, no need to add a nonce header.
  89          addNonceHeader = ! ( options.data && options.data._wpnonce );
  90          addAcceptHeader = true;
  91  
  92          headers = options.headers || {};
  93  
  94          for ( headerName in headers ) {
  95              if ( ! headers.hasOwnProperty( headerName ) ) {
  96                  continue;
  97              }
  98  
  99              // If an 'X-WP-Nonce' or 'Accept' header (or any case-insensitive variation
 100              // thereof) was specified, no need to add the header again.
 101              switch ( headerName.toLowerCase() ) {
 102                  case 'x-wp-nonce':
 103                      addNonceHeader = false;
 104                      break;
 105                  case 'accept':
 106                      addAcceptHeader = false;
 107                      break;
 108              }
 109          }
 110  
 111          if ( addNonceHeader ) {
 112              // Do not mutate the original headers object, if any.
 113              headers = $.extend( {
 114                  'X-WP-Nonce': wpApiSettings.nonce
 115              }, headers );
 116          }
 117  
 118          if ( addAcceptHeader ) {
 119              headers = $.extend( {
 120                  'Accept': 'application/json, */*;q=0.1'
 121              }, headers );
 122          }
 123  
 124          if ( typeof method === 'string' ) {
 125              method = method.toUpperCase();
 126  
 127              if ( 'PUT' === method || 'DELETE' === method ) {
 128                  headers = $.extend( {
 129                      'X-HTTP-Method-Override': method
 130                  }, headers );
 131  
 132                  method = 'POST';
 133              }
 134          }
 135  
 136          // Do not mutate the original options object.
 137          options = $.extend( {}, options, {
 138              headers: headers,
 139              url: url,
 140              method: method
 141          } );
 142  
 143          delete options.path;
 144          delete options.namespace;
 145          delete options.endpoint;
 146  
 147          return options;
 148      };
 149  
 150      apiRequest.transport = $.ajax;
 151  
 152      /** @namespace wp */
 153      window.wp = window.wp || {};
 154      window.wp.apiRequest = apiRequest;
 155  } )( jQuery );