Navigation

Integrate Third-Party Services

You can interact with external services directly from your client application or from a server-side function. Rules defined on the Stitch server for each service let you manage who can call specific service actions as well as what data can be sent to the service.

Call a Service from the Client

The stitch-quickstarts Amazon S3 bucket contains image files uploaded by the users of an application. In the following example, you can upload an image file from your computer to the stitch-quickstarts bucket using the S3 service. Once the upload is complete we immediately retrieve the image from S3 with the HTTP service and display it.

The S3 service validates every put action sent through the service with a service rule. This rule ensures that users can only upload images of a valid type (i.e. one of .png, .jpeg, or .gif) to the stitch-quickstarts bucket with an acl value of public-read.

s3Service.put() Service Action Rule
{
  "%%args.bucket": "stitch-quickstarts",
  "%%args.acl": "public-read",
  "%%args.contentType": { "%in": ["image/png", "image/jpeg", "image/gif"] }
}

Live Example

Try to upload a file that isn’t a .png, .jpeg, or .gif, or try changing the bucket name to something other than stitch-quickstarts. You should see a notification that a service rule prevented the action.

Call a Service from a Server Function

Some application logic must be handled on the server, such as generating and verifying secure access codes. In the following example, we use the Twilio Service to send users a device authentication code in a text message. Users can enter the code to prove that they own the phone number they entered.

All of the service logic is handled in two server-side functions. The first function, generate2faCode, generates a new device code, inserts a document containing the user’s code and phone number into MongoDB, and sends the user a text message with the code. The second function, check2faCode, formats the user’s phone number with a Twilio API, queries MongoDB for a document associated with the user’s phone number, and compares the user-submitted code to the code listed in the document to see if it matches.

generate2faCode
exports = function(phoneNumber) {
  const twilio = context.services.get("twilio");
  const code = generateDeviceCode();

  // Store the code in MongoDB then send it to the user in a text message
  linkCodeWithPhoneNumber(code, phoneNumber)
  .then(() => twilio.send({
     to: phoneNumber,
     from: context.values.get("ourPhoneNumber"),
     body: `Your Stitch 2fa code is: ${code}`
   }));
}
check2faCode
exports = function(phoneNumber, submittedCode){
  const atlas = context.services.get("mongodb-atlas");
  const twoFactorCodes = atlas.db("quickstart").collection("2fa");
  const formatPhoneNumber = number => context.functions.execute("lookupPhoneNumber", number)
    .then(response => EJSON.parse(response.body.text()).phone_number);

  return formatPhoneNumber(phoneNumber)
    .then(formattedNumber => {
      return twoFactorCodes.findOne({ phoneNumber: formattedNumber });
    })
    .then(doc => {
      const twoFactorCode = doc.current2fa.code;
      return twoFactorCode == submittedCode;
    });
};