HTTP

These functions can be used when opening and submitting remote web requests, and webhooks.

Response encoding and errors

Failed requests return descriptive errors with the relevant HTTP status code when the remote server provides one.

Response bodies encode SurrealQL values as follows:

• •

  Bytes, sent as raw bytes (not base64- or JSON-encoded).

• •

  Strings, sent as raw strings.

• •

  Other values (numbers, arrays, objects, booleans, and so on), JSON-encoded.

SurrealDB does not add Content-Type: application/octet-stream automatically when the body contains byte values. You can set this header yourself if a client requires it.

http::head

The http::head function performs a remote HTTP HEAD request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error.

http::head(string) -> null

If an object is given as the second argument, then this can be used to set the request headers.

http::head(string, $headers: object) -> null

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::head('https://surrealdb.com');

null

To specify custom headers with the HTTP request, pass an object as the second argument:

RETURN http::head('https://surrealdb.com', {
	'x-my-header': 'some unique string'
});

null

http::get

The http::get function performs a remote HTTP GET request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error.

If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::get(string) -> value

If an object is given as the second argument, then this can be used to set the request headers.

http::get(string, $headers: object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::get('https://surrealdb.com');

-- The HTML code is returned

To specify custom headers with the HTTP request, pass an object as the second argument:

RETURN http::get('https://surrealdb.com', {
	'x-my-header': 'some unique string'
});

-- The HTML code is returned

http::put

The http::put function performs a remote HTTP PUT request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::put(string, $body: object) -> value

If an object is given as the third argument, then this can be used to set the request headers.

http::put(string, $body: object, $headers: object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::put('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: 'eburras1q'
  }
});

RETURN http::put('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: 'eburras1q'
  }
}, {
  'Authorization': 'Bearer your-token-here',
  'Content-Type': 'application/json',
  'x-custom-header': 'custom-value'
});

{
	body: 'This is some awesome thinking!',
	id: 1,
	postId: 100,
	user: {
		id: 63,
		username: 'eburras1q'
	}
}

http::post

The http::post function performs a remote HTTP POST request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::post(string, $body: object) -> value

If an object is given as the third argument, then this can be used to set the request headers.

http::post(string, $body: object, $headers: object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::post('https://jsonplaceholder.typicode.com/posts/', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
});

RETURN http::post('https://jsonplaceholder.typicode.com/posts/', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
}, {
  'Authorization': 'Bearer your-token-here',
  'Content-Type': 'application/json',
  'x-custom-header': 'custom-value'
});

{
	body: 'This is some awesome thinking!',
	id: 101,
	postId: 100,
	user: {
		id: 63,
		username: 'eburras1q'
	}
}

http::patch

The http::patch function performs a remote HTTP PATCH request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::patch(string, $body: object) -> value

If an object is given as the third argument, then this can be used to set the request headers.

http::patch(string, $body: object, $headers: object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::patch('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
});

RETURN http::patch('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
}, {
  'Authorization': 'Bearer your-token-here',
  'Content-Type': 'application/json',
  'x-custom-header': 'custom-value'
});

{
	body: 'This is some awesome thinking!',
	id: 1,
	postId: 100,
	title: 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit',
	user: {
		id: 63,
		username: 'eburras1q'
	},
	userId: 1
}

http::delete

The http::delete function performs a remote HTTP DELETE request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::delete(string) -> value

If an object is given as the second argument, then this can be used to set the request headers.

http::delete(string, $headers: object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::delete('https://jsonplaceholder.typicode.com/posts/1');

{}

To specify custom headers with the HTTP request, pass an object as the second argument:

RETURN http::delete('https://jsonplaceholder.typicode.com/posts/1', {
	'x-my-header': 'some unique string'
});

{}