http.post()

On this page

Definition

Usage
Example
Parameters
Return Value
Rule Templates
Users Can Only Send Requests to a Specific Host
Requests URLs Must Include a Specific Query Parameter
Request Bodies Must Include a Specific Field
Request Bodies Must Include Fields with Specific Values

Atlas Device Sync, Atlas Edge Server, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

Definition

http.post()

Sends an HTTP POST request to the specified URL using the Atlas App Services HTTP Service.

Usage

Example

Note

This example assumes you have configured an HTTP service called "myHttp". If you do not need this HTTP action validated with Service Rules, you can use the Send an HTTP Request (context.http) module.

exports = function() {
  const http = context.services.get("myHttp");
  return http.post({
      url: "https://www.example.com/messages",
      body: { msg: "This is in the body of a POST request!" },
      encodeBodyAsJSON: true
    })
    .then(response => {
      // The response body is encoded as raw BSON.Binary. Parse it to JSON.
      const ejson_body = EJSON.parse(response.body.text());
      return ejson_body;
    })
};

Parameters

The http.post() action accepts one argument of the following form:

{
    "url": <string>,
    "headers": <document>,
    "body": <object> or <string>,
    "encodeBodyAsJSON": <boolean>,
    "form": <document>,
    "cookies": <string>,
    "authUrl": <string>,
    "followRedirects": <boolean>
}

Field

Description

Request URL

url: <string>

Required. The target URL for the HTTP request. Alternatively, you can specify the components of the URL as root-level fields. See Alternative URL Arguments.

Request Body

body: <object> or <string>

Required. The object or stringified body of the HTTP request. If the request payload has a content type of multipart/form-data, use the form parameter instead of body. If the request body is an object, the encodeBodyAsJSON parameter must be true.

Encode Body as JSON

encodeBodyAsJSON: <boolean>

If true, the body is automatically encoded as an EJSON string using EJSON.stringify(). Only use when the body parameter is an object.

Form Request Body

form: <document>

A document where each field maps to a field in a multipart/form-data request. You cannot use this parameter at the same time as the body parameter.

Note

Requests that use the form parameter should also include a Content-Type: multipart/form-data header.

Example

"form": {
  "to-address": "name@example.com",
  "from-address": "other-name@example.com",
  "subject": "test subject please ignore",
  "message-body": "hello from the message body"
}

Request Headers

headers: <document>

Optional. A document where each field name corresponds to a type of HTTP header and each field value is an array of one or more string values for that header.

Example

{
  "Content-Type": [ "application/json" ]
}

Request Cookies

cookies: <document>

Optional. A document where each field name corresponds to a cookie name and each field value is that cookie's string value.

Example

{
  "favoriteTeam": "Chicago Cubs"
}

Digest Authentication

digestAuth: <boolean>

Optional. If true, App Services authenticates the request using digest authentication. You must specify a username and password (either as fields in the request document or as part of the URL) to use digest authentication. For more details, see Request Authentication.

Request Authentication URL

authUrl: <string>

Optional. A URL that returns an Authorization cookie for the HTTP request.

Follow Redirects

followRedirects: <boolean>

Optional. If true, the request will follow any HTTP redirects it receives for the target URL.

Alternative URL Parameters

If you need to specify the individual components of the request's target URL, omit the url field and specify the components as root-level fields. The following URL component fields are available:

<scheme>://<host>/<path>?<query>#<fragment>

{
   "scheme": <string>,
   "host": <string>,
   "path": <string>,
   "query": <document>,
   "fragment": <string>,
   "username": <string>,
   "password": <string>
}

Name

Contents

scheme

Optional. Default: "http".

Valid options: https, http

The URL scheme.

Example

// https://www.example.com/
{ scheme: "https" }

host

Required.

The hostname of the target resource.

Example

// https://www.example.com/
{ host: "www.example.com" }

path

Optional.

The path of the target resource.

Example

// https://www.example.com/api/v1/users
{ path: "/api/v1/users" }

query

Optional.

A document where each field maps to a parameter in the URL query string. The value of each field is an array of strings that contains all arguments for the parameter.

Example

// https://www.example.com/?id=8675309&color=red&color=blue
{
  query: {
    "id": ["8675309"],
    "color": ["red", "blue"]
  }
}

fragment

Optional.

The URL fragment. This portion of the URL includes everything after the hash (#) symbol.

Example

// https://www.example.com/?id=8675309#someFragment
{ fragment: "someFragment" }

username

Optional.

The username with which to authenticate the request. Typically, users utilize this argument with the password argument.

password

Optional.

The password with which to authenticate the request. The password should correspond to the user specified in the username argument.

Return Value

The http.post() action returns a promise that resolves to a document with the following form:

{
   "status": <string>,
   "statusCode": <integer>,
   "contentLength": <integer>,
   "headers": <document>,
   "cookies": <array>,
   "body": <binary>
}

Field

Type

Description

status

string

The HTTP Request status message.

statusCode

integer

The HTTP Request status code.

contentLength

integer

The number of bytes returned in the response body.

headers

document

A document where each field name corresponds to a type of HTTP header and each field value is an array of one or more string values for that header.

Example

{
  "Content-Type": [ "application/json" ]
}

cookies

document

A document where each field name corresponds to a cookie name, and each field value is that cookie's string value.

Example

{
  "favoriteTeam": "Chicago Cubs"
}

body

binary

The binary-encoded body of the HTTP response.

Request Authentication

You can authenticate an outbound HTTP request using one of the standard HTTP authentication schemes. Atlas App Services supports the following authentication schemes:

Basic Authentication

HTTP basic authentication requires that incoming requests include a valid username and password for the requested service. You can specify the user credentials in the username and password fields of the request document, directly in a url string, or in an Authorization HTTP header.

Example

The following examples demonstrate three equivalent ways to authenticate an HTTP service request using basic authentication. The examples all use the username MyUser and the password Mypassw0rd. You would pass one of these objects as an argument to the given HTTP method.

Specify Credentials Directly (Best Method)

{
  "scheme": "https",
  "username": "MyUser",
  "password": "Mypassw0rd",
  "domain": "www.example.com"
}

Embed Credentials in the URL

{
  "url": "https://MyUser:Mypassw0rd@www.example.com"
}

Include an Authorization Header

{
  "url": "https://www.example.com",
  "headers": {
    "Authorization": [
      `Basic ${BSON.Binary.fromText("MyUser:Mypassw0rd").toBase64()}`
    ]
  }
}

Digest Authentication

HTTP digest authentication requires that incoming requests include an authorization key based on a random nonce value returned from the server. App Services can automatically construct the key and authorize requests given a valid username and password.

To configure a request to use digest authentication, set the digestAuth field to true and specify the user credentials in the username and password fields of the request document or directly in a url string.

Example

The following examples demonstrate two equivalent ways to authenticate an HTTP service request using digest authentication. The examples all use the username MyUser and the password Mypassw0rd.

Specify Credentials Directly (Best Method)

{
  "scheme": "https",
  "username": "MyUser",
  "password": "Mypassw0rd",
  "domain": "www.example.com",
  "digestAuth": true
}

Embed Credentials in the URL

{
  "url": "https://MyUser:Mypassw0rd@www.example.com",
  "digestAuth": true
}

Rule Templates

Users Can Only Send Requests to a Specific Host

{
  "%%args.url.host": "example.com"
}

Requests URLs Must Include a Specific Query Parameter

{
  "%%args.url.query.someParameter": "importantValue"
}

Request Bodies Must Include a Specific Field

{
  "body.name": { "%exists": 1 }
}

Request Bodies Must Include Fields with Specific Values

{
  "body.city": "New York City"
}

Back

http.get()

http.put()