m3api-rest 0.1.1 → 0.2.0

package/CHANGES.md

@@ -5,6 +5,57 @@ This file records the changes in each m3api-rest release.
 The annotated tag (and GitLab release) for each version also lists the changes,
 but this file may sometimes contain later improvements (e.g. typo fixes).
 
+## v0.2.0 (2026-04-05)
+
+- Major functionality update:
+  beyond `getJson()` and `postForJson()`,
+  m3api-rest now supports the following:
+    - request methods:
+      - GET
+      - POST
+      - PUT
+      - DELETE
+      - PATCH
+    - request body content types:
+      - `application/json`
+      - `application/x-www-form-urlencoded`
+      - `multipart/form-data`
+    - response body content types:
+      - `application/json`
+      - `text/plain`
+      - `text/html`
+
+  Yielding the following full list of request functions:
+    - `getJson()`
+    - `getText()`
+    - `getHtml()`
+    - `postForJson()`
+    - `postForText()`
+    - `postForHtml()`
+    - `putForJson()`
+    - `putForText()`
+    - `putForHtml()`
+    - `deleteForJson()`
+    - `deleteForText()`
+    - `deleteForHtml()`
+    - `patchForJson()`
+    - `patchForText()`
+    - `patchForHtml()`
+- BREAKING CHANGE:
+  `getJson()` and `postForJson()` can now return `String` instances
+  in addition to objects and arrays,
+  if the server returns JSON-encoded strings.
+  (This is unlikely for MediaWiki core’s REST API endpoints,
+  but common in the Wikibase REST API.)
+- BREAKING CHANGE:
+  The `body` property of the `RestApiServerError`,
+  `RestApiClientError` and `UnexpectedResponseStatus` classes
+  is now documented with the type `*` (“any”) rather than `string|Object`.
+  The previous type was incorrect – if the server response is JSON,
+  m3api-rest just decodes it for the error without checking if it’s an object or not.
+  (You almost certainly don’t need to care about this change,
+  but it’s technically breaking.)
+
 ## v0.1.1 (2026-04-05)
 
 - Updated the library for the new network interface of m3api v1.1.0,

package/README.md

@@ -3,22 +3,14 @@
 m3api-rest is an extension package for [m3api],
 allowing you to interact with the MediaWiki REST API.
 
-## Request functions
+## Usage examples
 
-m3api-rest includes functions to make GET and POST requests that return JSON responses.
-Other request methods and response content types will be added in future versions.
-All functions start with the HTTP method name (in lowercase);
-for GET functions, this is directly followed by the response type (e.g. `getJson`),
-while other functions have the word “for” in between (e.g. `postForJson`)
-to clarify that this is the response content type, not the request content type.
-(The content type of the request body is specified by the type of the body passed into the function;
-currently `postForJson` only supports `URLSearchParams` bodies,
-but in future versions the same function will support multiple body types.)
+Before digging into all the available features in m3api-rest,
+let’s start with some examples for commonly used functions.
 
 ### `getJson`
 
 Make a GET request for some JSON data.
-Usage examples:
 
 ```js
 import Session from 'm3api';
@@ -46,7 +38,23 @@ See also below for details on the different ways to specify parameters.
 ### `postForJson`
 
 Make a POST request that will return some JSON data.
-Usage example:
+
+```js
+const session = new Session( 'test.wikipedia.org', {}, {
+	userAgent: 'm3api-rest-README-example',
+	accessToken: ...,
+} );
+
+const title = 'Test page',
+	source = 'Test page contents',
+	comment = 'test edit';
+const response = await postForJson( session, '/v1/page', {
+	title,
+	source,
+	comment,
+} );
+console.log( `Created new page with page ID ${ response.id }` );
+```
 
 ```js
 const wikitext = '== ==\nThis is <span id=id>bad</span> <span id=id>wikitext</span>.';
@@ -56,12 +64,112 @@ const lints = await postForJson( session, '/v1/transform/wikitext/to/lint', new
 console.log( lints ); // [ { type: 'empty-heading', ... }, { type: 'duplicate-ids', ... } ]
 ```
 
-(Note that some endpoints, including `POST /v1/page`, cannot be used yet,
-because m3api-rest can currently only send `application/x-www-form-urlencoded` request bodies
-but those endpoints require `application/json`.
-This will be fixed in a future version.)
+### `putForJson`
+
+Make a PUT request that will return some JSON data.
+
+```js
+// session should still have an accessToken, like in the previous example
+const title = 'Test page';
+const page = await getJson( session, path`/v1/page/${ title }` );
+const updatedPage = await putForJson( session, path`/v1/page/${ title }`, {
+	source: page.source.replace( /privledge/g, 'privilege' ), // example typo fix
+	comment: 'test edit',
+	content_model: page.content_model,
+	latest: page.latest,
+} );
+console.log( `Edited page with revision ID ${ updatedPage.latest.id }` );
+```
+
+### `getHtml`
+
+Make a GET request that will return HTML.
+The HTML is returned as a `String`;
+if you want to turn it into a DOM, you will need to parse it yourself,
+e.g. using a [`DOMParser`][] in the browser or [jsdom][] on Node.js.
+
+```js
+const title = 'Douglas Adams';
+const html = await getHtml( session, path`/v1/page/${ title }/html` );
+const dom = new DOMParser().parseFromString( html, 'text/html' );
+const rudimentaryLeadParagraph = dom.querySelector( 'p:not( .mw-empty-elt )' );
+```
+
+### `postForText`, `postForHtml`
+
+Make GET requests that will return text or HTML, respectively.
+As with `getHtml`, the result is returned as a `String`.
+You can use these functions to convert between wikitext and HTML, for instance.
+
+```js
+const wikitext = "''Hello, world!''";
+const html = await postForHtml( session, '/v1/transform/wikitext/to/html', {
+	wikitext,
+} );
+console.log( html.valueOf() );
+// <!DOCTYPE html>...<i ...>Hello, world!</i>
+const wikitext2 = await postForText( session, '/v1/transform/html/to/wikitext', {
+	html,
+} );
+console.log( wikitext2.valueOf() );
+// ''Hello, world!''
+```
+
+## Request functions
 
-## Specifying parameters
+m3api-rest supports the following:
+
+- request methods:
+  - GET
+  - POST
+  - PUT
+  - DELETE
+  - PATCH
+- request body content types:
+  - `application/json`
+  - `application/x-www-form-urlencoded`
+  - `multipart/form-data`
+- response body content types:
+  - `application/json`
+  - `text/plain`
+  - `text/html`
+
+### Request methods and response body content types
+
+Each combination of request method and response body content type has a separate function,
+whose name begins with the HTTP method name (in lowercase).
+For GET functions, this is directly followed by the response type (e.g. `getJson`),
+while other functions have the word “for” in between (e.g. `postForJson`)
+to clarify that this is the response body content type, not the request body content type.
+The response body content types are “json”, “text”, or “html”,
+and included in the method name with an initial uppercase letter
+(e.g. `getJson`, `postForText`, `postForHtml`).
+Overall, the following functions are available:
+
+- `getJson`
+- `getText`
+- `getHtml`
+- `postForJson`
+- `postForText`
+- `postForHtml`
+- `putForJson`
+- `putForText`
+- `putForHtml`
+- `deleteForJson`
+- `deleteForText`
+- `deleteForHtml`
+- `patchForJson`
+- `patchForText`
+- `patchForHtml`
+
+### Request body content types
+
+The request body type for non-GET request functions is determined
+by the type of the object passed into the function,
+i.e. the same function (e.g. `postForJson`) can send request bodies encoded in different ways.
+For details, see the section on “body parameters” below.
+
+### Specifying parameters
 
 REST API endpoints have different kinds of parameters.
 Many endpoints take parameters in the path, written like `/v1/page/{title}` (`title` is a parameter);
@@ -69,7 +177,7 @@ many endpoints take query parameters after the path, like `/v1/search/page?q=sea
 and non-GET endpoints (POST etc.) take body parameters in several encodings.
 m3api-rest supports several ways to specify these parameters.
 
-### Path parameters
+#### Path parameters
 
 Path parameters can be specified using a tagged template literal (string template)
 using the `path` function,
@@ -98,7 +206,7 @@ const page = await getJson( session, '/v1/page/{title}', {
 // makes a request to /v1/page/AC%2FDC?redirect=true
 ```
 
-### Query parameters
+#### Query parameters
 
 The GET request functions, e.g. `getJson`, take an object with query parameters after the path:
 
@@ -119,31 +227,57 @@ you should pass them into the `path` as an object:
 
 ```js
 const params = { fakeQueryParam: 'abc' };
-await postForJson( path`/v0/fake/endpoint?${ params }`, new URLSearchParams( {
+await postForJson( path`/v0/fake/endpoint?${ params }`, {
 	fakeBodyParam: 'xyz',
-} ) );
-// makes a request to /v0/fake/endpoint?fakeQueryParam=abc with fakeBodyParam=xyz in the body
+} );
+// makes a request to /v0/fake/endpoint?fakeQueryParam=abc with {"fakeBodyParam":"xyz"} in the body
 ```
 
 This is also possible for GET requests, but you should probably prefer passing the query parameters separately there.
 
-### Body parameters
+#### Body parameters
 
-The non-GET request functions, e.g. `postForJson`, take a value for the body after the path.
-The type of the value encodes the content type with which the body will be sent.
-Currently, the only supported type is `URLSearchParams`,
-which will send the body as `application/x-www-form-urlencoded`;
-support for other body types
-(`FormData` for `multipart/form-data`, plain object for `application/json`)
-will be added in a future version.
+The non-GET request functions, e.g. `postForJson`, take a value for the request body after the path.
+The type of the value encodes the content type with which the request body will be sent:
+a plain object is sent as `application/json`;
+a `URLSearchParams` instance is sent as `application/x-www-form-urlencoded`;
+and a `FormData` instance is sent as `multipart/form-data`.
 
 ```js
-const lints = await postForJson( session, '/v1/transform/wikitext/to/lint', new URLSearchParams( {
-	wikitext: 'some wikitext',
-} ) );
-/// makes a request to /v1/transform/wikitext/to/lint with wikitext=some%20wikitext
+const wikitext = "''Hello, world!''";
+
+// send as application/json
+const html = await postForHtml(
+	session,
+	'/v1/transform/wikitext/to/html',
+	{
+		wikitext,
+	},
+);
+
+// send as application/x-www-form-urlencoded
+const html = await postForHtml(
+	session,
+	'/v1/transform/wikitext/to/html',
+	new URLSearchParams( {
+		wikitext,
+	} ),
+);
+
+// send as multipart/form-data
+const formData = new FormData();
+formData.set( 'wikitext', wikitext );
+const html = await postForHtml(
+	session,
+	'/v1/transform/wikitext/to/html',
+	formData,
+);
 ```
 
+Note that not all REST API endpoints accept all request body content types.
+Generally speaking, JSON is your safest bet,
+but you should consult the API endpoint’s documentation to see what request bodies it accepts.
+
 As mentioned above, you can also specify path parameters here.
 
 ## License
@@ -153,4 +287,6 @@ By contributing to this software,
 you agree to publish your contribution under the same license.
 
 [m3api]: https://www.npmjs.com/package/m3api
+[`DOMParser`]: https://developer.mozilla.org/en-US/docs/Web/API/DOMParser
+[jsdom]: https://www.npmjs.com/package/jsdom
 [ISC License]: https://spdx.org/licenses/ISC.html

package/index.js

@@ -5,7 +5,7 @@ export class RestApiServerError extends Error {
 
 	/**
 	 * @param {number} status The invalid status code received from the API.
-	 * @param {string|Object} body The response body received from the API.
+	 * @param {*} body The response body received from the API.
 	 */
 	constructor( status, body ) {
 		super( `REST API server error: ${ status }\n\n${ JSON.stringify( body ) }` );
@@ -27,9 +27,9 @@ export class RestApiServerError extends Error {
 		 * The body of the response.
 		 *
 		 * Depending on the response’s content type,
-		 * this may be a string or a JSON-decoded object.
+		 * this may be a string or a JSON-decoded value.
 		 *
-		 * @member {string|Object}
+		 * @member {*}
 		 */
 		this.body = body;
 	}
@@ -43,7 +43,7 @@ export class RestApiClientError extends Error {
 
 	/**
 	 * @param {number} status The invalid status code received from the API.
-	 * @param {string|Object} body The response body received from the API.
+	 * @param {*} body The response body received from the API.
 	 */
 	constructor( status, body ) {
 		super( `REST API client error: ${ status }\n\n${ JSON.stringify( body ) }` );
@@ -65,9 +65,9 @@ export class RestApiClientError extends Error {
 		 * The body of the response.
 		 *
 		 * Depending on the response’s content type,
-		 * this may be a string or a JSON-decoded object.
+		 * this may be a string or a JSON-decoded value.
 		 *
-		 * @member {string|Object}
+		 * @member {*}
 		 */
 		this.body = body;
 	}
@@ -83,7 +83,7 @@ export class UnexpectedResponseStatus extends Error {
 
 	/**
 	 * @param {number} status The unexpected status code received from the API.
-	 * @param {string|Object} body The response body received from the API.
+	 * @param {*} body The response body received from the API.
 	 */
 	constructor( status, body ) {
 		super( `Unexpected REST API response status: ${ status }\n\n${ JSON.stringify( body ) }` );
@@ -105,9 +105,9 @@ export class UnexpectedResponseStatus extends Error {
 		 * The body of the response.
 		 *
 		 * Depending on the response’s content type,
-		 * this may be a string or a JSON-decoded object.
+		 * this may be a string or a JSON-decoded value.
 		 *
-		 * @member {string|Object}
+		 * @member {*}
 		 */
 		this.body = body;
 	}
@@ -292,6 +292,25 @@ export class InvalidPathParams extends Error {
 
 }
 
+/**
+ * Get the MIME type (e.g. application/json) of the given response.
+ *
+ * @private
+ * @param {Response} response
+ * @return {string} The mime type part of the Content-Type response header,
+ * not including parameters like ;charset=utf-8
+ */
+function getResponseMimeType( response ) {
+	const contentType = response.headers.get( 'Content-Type' );
+	const [ mimeType ] = contentType.split( ';', 1 );
+	// this accepts some technically invalid Content-Type headers
+	// (we don’t check if the part before ; is a valid media-type,
+	// i.e. two tokens separated by a slash,
+	// cf. https://httpwg.org/specs/rfc9110.html#media.type)
+	// because there’s no reason to reject them
+	return mimeType;
+}
+
 /**
  * Determine whether this response contains JSON
  * according to its headers.
@@ -301,14 +320,37 @@ export class InvalidPathParams extends Error {
  * @return {boolean}
  */
 function isResponseJson( response ) {
-	const contentType = response.headers.get( 'Content-Type' );
-	const [ mimeType ] = contentType.split( ';', 1 ); // split off ;charset=utf-8 and suchlike
+	const mimeType = getResponseMimeType( response );
 	return mimeType === 'application/json' ||
 		( mimeType.startsWith( 'application/' ) && mimeType.endsWith( '+json' ) );
-	// this accepts some technically invalid Content-Type headers
-	// (we don’t check if the part before +json is a valid subtype / token,
-	// cf. https://httpwg.org/specs/rfc9110.html#media.type)
-	// because there’s no reason to reject them
+}
+
+/**
+ * Determine whether this response contains text
+ * (“plain text”, but in practice often wikitext) according to its headers.
+ *
+ * @private
+ * @param {Response} response
+ * @return {boolean}
+ */
+function isResponseText( response ) {
+	const mimeType = getResponseMimeType( response );
+	return mimeType === 'text/plain' ||
+		( mimeType.startsWith( 'text/' ) && mimeType.endsWith( '+plain' ) );
+}
+
+/**
+ * Determine whether this response contains HTML
+ * according to its headers.
+ *
+ * @private
+ * @param {Response} response
+ * @return {boolean}
+ */
+function isResponseHtml( response ) {
+	const mimeType = getResponseMimeType( response );
+	return mimeType === 'text/html' ||
+		( mimeType.startsWith( 'text/' ) && mimeType.endsWith( '+html' ) );
 }
 
 /**
@@ -316,7 +358,7 @@ function isResponseJson( response ) {
  *
  * @private
  * @param {Response} response
- * @return {string|Object}
+ * @return {*}
  */
 async function getResponseBodyForError( response ) {
 	if ( isResponseJson( response ) ) {
@@ -350,7 +392,7 @@ const responseStatuses = new WeakMap();
 /**
  * Get the HTTP status code for this response.
  *
- * @param {Object|Array} response A response object returned by one of the request functions
+ * @param {Object|Array|String} response A response object returned by one of the request functions
  * ({@link getJson} etc.). Note that it must be exactly the object returned by the function
  * (compared by identity, i.e. `===`), not a serialization of it or anything similar.
  * @return {number} The HTTP status code, i.e. an integer between 200 and 599.
@@ -369,17 +411,21 @@ export function getResponseStatus( response ) {
  *
  * @private
  * @param {Response} response
- * @return {Object|Array}
+ * @return {Object|Array|String}
  */
 async function getResponseJson( response ) {
 	if ( isResponseJson( response ) ) {
 		const body = await response.json();
+		let bodyWithIdentity;
 		if ( typeof body === 'object' && body !== null ) {
-			responseStatuses.set( body, response.status );
-			return body;
+			bodyWithIdentity = body;
+		} else if ( typeof body === 'string' ) {
+			bodyWithIdentity = new String( body );
 		} else {
 			throw new InvalidResponseBody( body );
 		}
+		responseStatuses.set( bodyWithIdentity, response.status );
+		return bodyWithIdentity;
 	} else {
 		throw new IncompatibleResponseType(
 			'application/json',
@@ -389,6 +435,49 @@ async function getResponseJson( response ) {
 	}
 }
 
+/**
+ * Get the body of the response and check that it’s valid text
+ * (“plain text”, but in practice often wikitext.)
+ *
+ * @private
+ * @param {Response} response
+ * @return {String}
+ */
+async function getResponseText( response ) {
+	if ( isResponseText( response ) ) {
+		const text = new String( await response.text() );
+		responseStatuses.set( text, response.status );
+		return text;
+	} else {
+		throw new IncompatibleResponseType(
+			'text/plain',
+			response.headers.get( 'Content-Type' ),
+			await getResponseBodyForError( response ),
+		);
+	}
+}
+
+/**
+ * Get the body of the response and check that it’s valid HTML.
+ *
+ * @private
+ * @param {Response} response
+ * @return {String}
+ */
+async function getResponseHtml( response ) {
+	if ( isResponseHtml( response ) ) {
+		const html = new String( await response.text() );
+		responseStatuses.set( html, response.status );
+		return html;
+	} else {
+		throw new IncompatibleResponseType(
+			'text/html',
+			response.headers.get( 'Content-Type' ),
+			await getResponseBodyForError( response ),
+		);
+	}
+}
+
 /**
  * Encode a path for a REST API endpoint.
  *
@@ -439,7 +528,7 @@ export function path( strings, ...values ) {
  *
  * @private
  * @param {string} path The path with optional `{param}` expressions.
- * @param {Object|URLSearchParams} params The input params. Not modified.
+ * @param {Object|URLSearchParams|FormData} params The input params. Not modified.
  * @return {Object} The potentially modified path and params.
  */
 function substitutePathParams( path, params ) {
@@ -463,6 +552,38 @@ function substitutePathParams( path, params ) {
 			}
 			copiedParams.delete( paramName );
 			return encodeURIComponent( values[ 0 ] );
+		} else if ( params instanceof FormData ) {
+			if ( copiedParams === null ) {
+				copiedParams = new FormData();
+				for ( const [ name, value ] of params.entries() ) {
+					copiedParams.append( name, value );
+				}
+			}
+			const values = copiedParams.getAll( paramName );
+			if ( values.length !== 1 ) {
+				throw new InvalidPathParams(
+					values.length === 0 ?
+						`Unspecified path param ${ match }` :
+						`Ambiguous path param ${ match }`,
+					path,
+					paramName,
+					params,
+				);
+			}
+			copiedParams.delete( paramName );
+			const value = values[ 0 ];
+			if ( value instanceof Blob ) {
+				// in practice, value will almost always be a File here,
+				// as FormData will turn any Blob into a File (except on old Node versions),
+				// hence the unspecific “Blob or File” in the message
+				throw new InvalidPathParams(
+					`Path param ${ match } cannot be a Blob or File`,
+					path,
+					paramName,
+					params,
+				);
+			}
+			return encodeURIComponent( value );
 		} else {
 			if ( copiedParams === null ) {
 				copiedParams = { ...params };
@@ -484,6 +605,44 @@ function substitutePathParams( path, params ) {
 	return { path: substitutedPath, params: copiedParams || params };
 }
 
+/**
+ * Convenience function to add a request header to the given `fetch()` options.
+ *
+ * @private
+ * @param {RequestInit} fetchOptions
+ * @param {string} name
+ * @param {string} value
+ */
+function addHeaderToOptions( fetchOptions, name, value ) {
+	fetchOptions.headers = new Headers( fetchOptions.headers );
+	fetchOptions.headers.set( name, value );
+}
+
+/**
+ * Prepare a GET request for the given parameters.
+ * Encodes the params into the URL and sets up request headers.
+ *
+ * @private
+ * @param {Session} session
+ * @param {string} path
+ * @param {Object} params
+ * @param {Options} options
+ * @return {Array} url and fetchOptions
+ */
+function prepareGetRequest( session, path, params, options ) {
+	( { path, params } = substitutePathParams( path, params ) );
+	const restUrl = session.apiUrl.replace( /api\.php$/, 'rest.php' );
+	const url = new URL( restUrl + path );
+	for ( const [ name, value ] of Object.entries( params || {} ) ) {
+		url.searchParams.append( name, value );
+	}
+	const fetchOptions = {
+		method: 'GET',
+		headers: session.getRequestHeaders( options ),
+	};
+	return [ url, fetchOptions ];
+}
+
 /**
  * Make a GET request to a REST API endpoint and return the JSON-decoded body.
  *
@@ -494,25 +653,129 @@ function substitutePathParams( path, params ) {
  * @param {Object} [params] Parameters for the request URL.
  * This may include both parameters for the path and query parameters.
  * @param {Options} [options] Request options.
- * @return {Object|Array} The body of the API response, JSON-decoded.
+ * @return {Object|Array|String} The body of the API response, JSON-decoded.
+ * If the API returned a string, then for technical reasons it will be returned
+ * as a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
  */
 export async function getJson( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = prepareGetRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'application/json' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseJson( response );
+}
+
+/**
+ * Make a GET request to a REST API endpoint and return the text body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object} [params] Parameters for the request URL.
+ * This may include both parameters for the path and query parameters.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function getText( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = prepareGetRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/plain' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseText( response );
+}
+
+/**
+ * Make a GET request to a REST API endpoint and return the HTML body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path, e.g. `/v1/page/{title}/html`.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object} [params] Parameters for the request URL.
+ * This may include both parameters for the path and query parameters.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function getHtml( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = prepareGetRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/html' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseHtml( response );
+}
+
+/**
+ * Encode a body for the request to the server.
+ *
+ * @param {Object|URLSearchParams|FormData} body
+ * @return {RequestInit} To be mixed into the `fetch()` options.
+ */
+function encodeBody( body ) {
+	if ( body instanceof URLSearchParams || body instanceof FormData ) {
+		return { body };
+	} else {
+		return {
+			body: JSON.stringify( body ),
+			headers: {
+				'Content-Type': 'application/json',
+			},
+		};
+	}
+}
+
+/**
+ * Prepare a non-GET request for the given parameters.
+ * Encodes the params into the URL and body and sets up request headers.
+ * The caller must set the specific method afterwards.
+ *
+ * @private
+ * @param {Session} session
+ * @param {string} path
+ * @param {Object} params
+ * @param {Options} options
+ * @return {Array} url and fetchOptions
+ */
+function prepareRequestWithBody( session, path, params, options ) {
 	( { path, params } = substitutePathParams( path, params ) );
 	const restUrl = session.apiUrl.replace( /api\.php$/, 'rest.php' );
 	const url = new URL( restUrl + path );
-	for ( const [ name, value ] of Object.entries( params || {} ) ) {
-		url.searchParams.append( name, value );
-	}
-	const headers = {
-		accept: 'application/json',
-		...session.getRequestHeaders( options ),
+	const fetchOptions = {
+		method: '', // trigger a TypeError in fetch() if caller does not override method
+		...encodeBody( params ),
 	};
-	const response = await session.fetch( url, {
-		method: 'GET',
-		headers,
-	} );
-	await checkResponseStatus( response );
-	return await getResponseJson( response );
+	fetchOptions.headers = new Headers( fetchOptions.headers );
+	for ( const [ name, value ] of Object.entries( session.getRequestHeaders( options ) ) ) {
+		fetchOptions.headers.set( name, value );
+	}
+	return [ url, fetchOptions ];
+}
+
+/**
+ * Prepare a POST request for the given parameters.
+ * Encodes the params into the URL and body and sets up request headers.
+ *
+ * @private
+ * @param {Session} session
+ * @param {string} path
+ * @param {Object} params
+ * @param {Options} options
+ * @return {Array} url and fetchOptions
+ */
+function preparePostRequest( session, path, params, options ) {
+	const [ url, fetchOptions ] = prepareRequestWithBody( session, path, params, options );
+	return [ url, {
+		...fetchOptions,
+		method: 'POST',
+	} ];
 }
 
 /**
@@ -522,27 +785,387 @@ export async function getJson( session, path, params, options = {} ) {
  * @param {string} path The resource path, e.g. `/v1/page`.
  * Does not include the domain, script path, or `rest.php` endpoint.
  * Use the {@link path} tag function to build the path.
- * @param {URLSearchParams} params The request body.
- * Will be sent using the `application/x-www-form-urlencoded` content type.
- * (Future versions of this library will support additional request body content types,
- * but that requires changes to m3api first.)
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
  * You may also include parameters for the path here.
  * @param {Options} [options] Request options.
- * @return {Object|Array} The body of the API response, JSON-decoded.
+ * @return {Object|Array|String} The body of the API response, JSON-decoded.
+ * If the API returned a string, then for technical reasons it will be returned
+ * as a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
  */
 export async function postForJson( session, path, params, options = {} ) {
-	( { path, params } = substitutePathParams( path, params ) );
-	const restUrl = session.apiUrl.replace( /api\.php$/, 'rest.php' );
-	const url = new URL( restUrl + path );
-	const headers = {
-		// accept: 'application/json', // skip this for now due to T412610
-		...session.getRequestHeaders( options ),
-	};
-	const response = await session.fetch( url, {
-		method: 'POST',
-		headers,
-		body: params,
-	} );
+	const [ url, fetchOptions ] = preparePostRequest( session, path, params, options );
+	// skip this for now due to T412610
+	// addHeaderToOptions( fetchOptions, 'accept', 'application/json' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseJson( response );
+}
+
+/**
+ * Make a POST request to a REST API endpoint and return the text body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path, e.g. `/v1/transform/html/to/wikitext`.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function postForText( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePostRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/plain' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseText( response );
+}
+
+/**
+ * Make a POST request to a REST API endpoint and return the HTML body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path, e.g. `/v1/transform/wikitext/to/html`.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function postForHtml( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePostRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/html' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseHtml( response );
+}
+
+/**
+ * Prepare a PUT request for the given parameters.
+ * Encodes the params into the URL and body and sets up request headers.
+ *
+ * @private
+ * @param {Session} session
+ * @param {string} path
+ * @param {Object} params
+ * @param {Options} options
+ * @return {Array} url and fetchOptions
+ */
+function preparePutRequest( session, path, params, options ) {
+	const [ url, fetchOptions ] = prepareRequestWithBody( session, path, params, options );
+	return [ url, {
+		...fetchOptions,
+		method: 'PUT',
+	} ];
+}
+
+/**
+ * Make a PUT request to a REST API endpoint and return the JSON-decoded body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path, e.g. `/v1/page/{title}`.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known PUT endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {Object|Array|String} The body of the API response, JSON-decoded.
+ * If the API returned a string, then for technical reasons it will be returned
+ * as a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function putForJson( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePutRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'application/json' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseJson( response );
+}
+
+/**
+ * Make a PUT request to a REST API endpoint and return the text body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known PUT endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function putForText( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePutRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/plain' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseText( response );
+}
+
+/**
+ * Make a PUT request to a REST API endpoint and return the HTML body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known PUT endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function putForHtml( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePutRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/html' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseHtml( response );
+}
+
+/**
+ * Prepare a DELETE request for the given parameters.
+ * Encodes the params into the URL and body and sets up request headers.
+ *
+ * @private
+ * @param {Session} session
+ * @param {string} path
+ * @param {Object} params
+ * @param {Options} options
+ * @return {Array} url and fetchOptions
+ */
+function prepareDeleteRequest( session, path, params, options ) {
+	const [ url, fetchOptions ] = prepareRequestWithBody( session, path, params, options );
+	return [ url, {
+		...fetchOptions,
+		method: 'DELETE',
+	} ];
+}
+
+/**
+ * Make a DELETE request to a REST API endpoint and return the JSON-decoded body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path, e.g. `/v1/page/{title}`.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known DELETE endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {Object|Array|String} The body of the API response, JSON-decoded.
+ * If the API returned a string, then for technical reasons it will be returned
+ * as a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function deleteForJson( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = prepareDeleteRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'application/json' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseJson( response );
+}
+
+/**
+ * Make a DELETE request to a REST API endpoint and return the text body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known DELETE endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function deleteForText( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = prepareDeleteRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/plain' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseText( response );
+}
+
+/**
+ * Make a DELETE request to a REST API endpoint and return the HTML body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known DELETE endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function deleteForHtml( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = prepareDeleteRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/html' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseHtml( response );
+}
+
+/**
+ * Prepare a PATCH request for the given parameters.
+ * Encodes the params into the URL and body and sets up request headers.
+ *
+ * @private
+ * @param {Session} session
+ * @param {string} path
+ * @param {Object} params
+ * @param {Options} options
+ * @return {Array} url and fetchOptions
+ */
+function preparePatchRequest( session, path, params, options ) {
+	const [ url, fetchOptions ] = prepareRequestWithBody( session, path, params, options );
+	return [ url, {
+		...fetchOptions,
+		method: 'PATCH',
+	} ];
+}
+
+/**
+ * Make a PATCH request to a REST API endpoint and return the JSON-decoded body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path, e.g. `/v1/page/{title}`.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known PATCH endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {Object|Array|String} The body of the API response, JSON-decoded.
+ * If the API returned a string, then for technical reasons it will be returned
+ * as a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function patchForJson( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePatchRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'application/json' );
+	const response = await session.fetch( url, fetchOptions );
 	await checkResponseStatus( response );
 	return await getResponseJson( response );
 }
+
+/**
+ * Make a PATCH request to a REST API endpoint and return the text body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known PATCH endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function patchForText( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePatchRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/plain' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseText( response );
+}
+
+/**
+ * Make a PATCH request to a REST API endpoint and return the HTML body.
+ *
+ * @param {Session} session The m3api session to use for this request.
+ * @param {string} path The resource path.
+ * Does not include the domain, script path, or `rest.php` endpoint.
+ * Use the {@link path} tag function to build the path.
+ * @param {Object|URLSearchParams|FormData} params The request body.
+ * An Object will be sent using the `application/json` content type;
+ * URLSearchParams will be sent using the `application/x-www-form-urlencoded` content type;
+ * FormData will be sent using the `multipart/form-data` content type.
+ * You may also include parameters for the path here.
+ * Note that all known PATCH endpoints only accept JSON bodies,
+ * so URLSearchParams or FormData params are unlikely to be useful.
+ * @param {Options} [options] Request options.
+ * @return {String} The body of the API response.
+ * For technical reasons, this is a `String` instance, not a primitive string value;
+ * you can mostly use it interchangeably with an ordinary string,
+ * or turn it into one by calling its `.valueOf()` method.
+ */
+export async function patchForHtml( session, path, params, options = {} ) {
+	const [ url, fetchOptions ] = preparePatchRequest( session, path, params, options );
+	addHeaderToOptions( fetchOptions, 'accept', 'text/html' );
+	const response = await session.fetch( url, fetchOptions );
+	await checkResponseStatus( response );
+	return await getResponseHtml( response );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "m3api-rest",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "m3api extension package to interact with the MediaWiki REST API.",
 	"main": "index.js",
 	"type": "module",