Make the Most of Your API Integrations
Learning Objectives
After completing this unit, you’ll be able to:
- Follow best practices for the REST and SOAP APIs.
- Use AMPscript, Server-side JavaScript, and Guide Template Language in conjunction with APIs.
- Implement available SDKs.
More API Tips and Resources
You know the basics for authenticating and working with the REST and SOAP APIs. (Woohoo!) Now, it’s time to take a look at some of the best ways to implement your API integrations, achieve peak performance, and handle any errors along the way.
Security
It’s no surprise that security tops the list when dealing with credentials and customer data. Follow these tips to make sure your interactions with Marketing Cloud Engagement are as secure as possible.
- Make sure that your OAuth token contains only the permissions necessary to accomplish your task.
- Treat your refresh token like credentials for a Salesforce account and keep it secure.
- Enforce TLS 1.2 when making requests to Marketing Cloud Engagement APIs.
- Use secure procedures to manage sessions for users—like using your framework’s session-management features.
- Verify session and permission levels for users in any apps you develop.
- Make sure users can access only what they need to perform their tasks.
- Make sure that you restrict stack traces and debug logs, so that only people who need the information can view it.
- Configure your system and requests to avoid common attacks like cross-site request forgery (CSRF), HTML injection and cross-site scripting (XSS), arbitrary redirects, and remote code execution.
- Update all libraries and frameworks frequently to help avoid security vulnerabilities.
- Follow industry-standard best practices when storing sensitive data like passwords, financial data, and other personally identifiable information.
Plan Your Requests
There’s always room to grow, so plan for your API integration to handle more data and data sources in the future. Here’s how.
- Reduce the number of steps to access, move, or update data to lower the number of requests to your API resources.
- If you know that your website or system regularly encounters high levels of activity, plan for those peaks and make sure your API integration can handle it.
- Test your code in a staging environment before moving to your production environment.
Data Management
To ease traffic, avoid simultaneous updates to a single data extension with multiple API requests. Instead, use a single request with all necessary information.
Use a coordinated universal time (UTC) offset to work with date and time values; then convert the time value when retrieving that information.
Include AMPscript, Server-Side JavaScript, and Guide Template Language
In addition to our APIs, Marketing Cloud Engagement includes three programmatic scripting languages that developers can use.
- AMPscript: A proprietary scripting language designed to personalize content for customers, provide dynamic content, and update subscriber information.
- Server-side JavaScript (SSJS): A language designed to mimic AMPscript functionality using syntax and functions similar to JavaScript.
- Guide Template Language (GTL): A language designed to build content and messages using Handlebars- and Moustache-style syntax.
As a developer, you’ll likely run across these programmatic languages as parts of messages or content included in requests from data extensions. For example, to include dynamic content in an email message, you might use GTL in the message to pull information from a data extension. You can store these scripts in data extensions as well.
AMPscript and SSJS can also call API functionality to build messages or create objects in Marketing Cloud Engagement. This AMPscript sample builds a sendable data extension using the SOAP API.
%%[
/*CREATE THE DATA EXTENSION*/
Set @de = CreateObject("DataExtension")
SetObjectProperty(@de,"Name","API-Created Data Extension")
SetObjectProperty(@de,"CustomerKey","XXXXXXXX")
SetObjectProperty(@de,"Description","Data Extension Created via API")
SetObjectProperty(@de,"IsSendable","True")
SetObjectProperty(@de,"IsTestable","False")
/*DE Folder ID - mouse over in app to get this ID */
SetObjectProperty(@de,"CategoryID","123")
/* THIS IS THE SENDABLE FIELD */
Set @deFields = CreateObject("DataExtensionField")
SetObjectProperty(@deFields,"FieldType","EmailAddress")
SetObjectProperty(@deFields,"IsRequired","true")
SetObjectProperty(@deFields,"IsPrimaryKey","true")
SetObjectProperty(@deFields,"IsNillable","false")
SetObjectProperty(@deFields,"MaxLength","100")
SetObjectProperty(@deFields,"Name","email_address")
AddObjectArrayItem(@de,"Fields",@deFields)
SetObjectProperty(@de,"SendableDataExtensionField",@deFields)
Set @deFields = CreateObject("DataExtensionField")
SetObjectProperty(@deFields,"FieldType","Text")
SetObjectProperty(@deFields,"IsRequired","true")
SetObjectProperty(@deFields,"IsPrimaryKey","false")
SetObjectProperty(@deFields,"IsNillable","false")
SetObjectProperty(@deFields,"MaxLength","100")
SetObjectProperty(@deFields,"Name","subscriber_key")
AddObjectArrayItem(@de,"Fields",@deFields)
Set @deFields = CreateObject("DataExtensionField")
SetObjectProperty(@deFields,"FieldType","Text")
SetObjectProperty(@deFields,"IsRequired","false")
SetObjectProperty(@deFields,"IsPrimaryKey","false")
SetObjectProperty(@deFields,"IsNillable","false")
SetObjectProperty(@deFields,"MaxLength","50")
SetObjectProperty(@deFields,"Name","first_name")
AddObjectArrayItem(@de,"Fields",@deFields)
Set @deFields = CreateObject("DataExtensionField")
SetObjectProperty(@deFields,"FieldType","Text")
SetObjectProperty(@deFields,"IsRequired","false")
SetObjectProperty(@deFields,"IsPrimaryKey","false")
SetObjectProperty(@deFields,"IsNillable","false")
SetObjectProperty(@deFields,"MaxLength","75")
SetObjectProperty(@deFields,"Name","last_name")
AddObjectArrayItem(@de,"Fields",@deFields)
/* This field sets how the data extension field above relates to the all subscribers list */
SET @ts_attr = CreateObject("Attribute")
SetObjectProperty(@ts_attr, "Name", "Email Address")
SetObjectProperty(@ts_attr, "Value", "Email Address")
SetObjectProperty(@de,"SendableSubscriberField",@ts_attr)
Set @StatCode = InvokeCreate(@de, @StatMessage, @ErrorCode)
]%%
Status = %%= v(@StatMessage) =%% -- %%= v(@ErrorCode) =%%
As always, test your code and scripts before deploying them, and use the version that works best for your needs.
Implement Marketing Cloud Engagement SDKs
Ready to assemble the necessary code for your integration? There are plenty of resources to help you get started and save time. (After all, who wants to start from scratch?) Get a leg up from your fellow developers and Marketing Cloud Engagement community with ready-to-use SDKs. Dig in to jumpstart your integration.
You can access community-supported SDKs for a variety of languages on GitHub. These SDKs include source code, samples, and documentation to get you started more quickly.
And, if you’re working with MobilePush or Content Builder, check out our app-specific SDKs.
With these tips and resources, you’ll be customizing your own integration in no time! And, as always, our community of Salesforce developers is here to help.