Create a Web Service

Learning Objectives

After completing this unit, you’ll be able to:

List the steps you can take to create a new web service.
Describe B2C Commerce Web Service framework best practices (timeout, circuit breaker, rate limit).
List the Business Manager configurations you must create for each web service.
Explain why web service names are important.
Explain the purpose of the service type.

Create a New Web Service

You learned about the Salesforce B2C Commerce Web Services framework in the previous unit. Now it’s time to learn about web services and how to create them.

You can take these steps to create a new web service for B2C Commerce third-party integrations.

Step	Task
1	Configure a web service in Business Manager.
2	Code a web service.
3	Set up logging and troubleshoot a web service.
4	Get it ready to go live.

Configure a Web Service

To integrate a third-party application via a web service, specify these credentials and web service profiles in Business Manager.

Configuration

Description

Web service

Specifies the credentials and web service profile that B2C Commerce uses when calling a web service. It generates a ServiceConfig object.

Web service credential

Is used for basic authentication.

Web service profile

Determines how B2C Commerce manages timeouts and rate limits for the web service. It defines how B2C Commerce detects and manages high numbers of requests to and responses from the service, as well as its availability. Different services with similar requirements can all use the same service profile.

When you configure a web service, you must create the credentials and profiles first. Then create the web service.

Names Are Important

When naming a service, it’s important to use an identifiable pattern, such as this: cartridge.protocol.service.operation

Here are some examples.

mycartridge.http.payment.get
mycartridge.ftp.partner.getPriceList

When service names contain periods, the period-delimited name segments become part of the logging hierarchy. Always include the cartridge in the name. This helps when you have multiple web service integrations, because it groups logging information and ensures unique service names.

You also need to take care when naming the prefix for the log file for your service. All logs are written in the shared log directory to a file named service-prefix-internalID-date.log.

If you don’t enter a prefix, the prefix name defaults to main, and the file is named service-main-serviceID-date.

These are examples. You can use your own naming convention.

Create Web Service Credentials

To access Business Manager, you must have a B2C Commerce implementation. In this module, we assume you have the proper permissions to perform these tasks. If you don’t, that’s OK. Read along to learn how you would take these steps in a staging instance. Don't try to follow our steps in your Trailhead Playground. B2C Commerce isn't available in the Trailhead Playground. If you have a staging instance of B2C Commerce, you can try out these steps in your instance. If you don't have a staging instance, ask the site administrator if there is one that you can use.

B2C Commerce uses web service credentials for basic authentication. Here’s how to specify credentials.

Open Business Manager.
Select Administration > Operations > Services.
Click the Credentials tab.
Click New.
Enter a name for the credential: test.mycartridge.http.partnerDon’t include spaces or user/password details.
Enter the URL to the service, including the protocol. For example: http://51.134.145.10To use one service configuration for several URIs, you can extend or alter the URL using getURL callback in the service registry definition.
Enter the username for the credential: s-architect
Enter the password: StringliGhtd1The password is masked after you type it and can't be retrieved from Business Manager. Store the value securely elsewhere.
Click Apply.

You can skip the operation part of the service name. This lets you use the same credential for multiple operations that are executed through the same service.

Configure a Web Service Profile

The web service profile defines how B2C Commerce detects and manages high numbers of requests to and responses from the service and its availability. Different services with similar requirements can use the same service profile. The following Business Manager web service profile settings are considered Web Services framework best practices.

Timeout

Specify the timeout in milliseconds. This value is used for both the connection and socket timeout of any internal connection. If B2C Commerce receives no response within this time, it throws an error.

The total run time of a service can be longer than the timeout, as long as individual responses don't exceed it. For example, consider a 5000-ms timeout. A 4-second connection attempt, followed by reading two chunks of data at 4 seconds apiece, takes about 13 seconds total. Because none of the individual communications exceeded 5 seconds, the process does not time out.

Service Type

When you create a web service configuration in Business Manager, you must select a service type. The service type determines the underlying class used to call your web service and adds methods to those inherited from the Service class.

Type	Class
HTTP	`dw.net.HTTPClient`
HTTP Form	`dw.net.HTTPClient`
FTP	`dw.net.FTPClient`
SFTP	`dw.net.SFTPClient`
SOAP	`dw.ws.webReference2`
Generic	Does not wrap any class.

Circuit Breaker

Circuit breakers provide an extra level of protection on top of the default behavior. They identify when a service is unavailable and stop making calls to the web service. The best practice is to enable the circuit breaker and configure it according to the service call rate. Here’s what you can specify in Business Manager.

The number of calls that must fail to trigger the circuit breaker. You must also set a value for the Circuit Breaker Interval (ms). Otherwise, leave both fields empty.
The number of milliseconds in which the maximum number of calls can fail. You must also set a value for the Max Circuit Breaker Calls field. Otherwise, leave both fields empty.

Rate Limit

This setting limits the number of outgoing calls within a specific interval. You can specify:

The maximum number of calls that B2C Commerce makes for the interval.
The number of milliseconds in which B2C Commerce can make the maximum number of calls to the web service.

Configure a Profile

Here’s how to configure a web service profile.

Open Business Manager.
Select Administration > Operations > Services.
Click the Profiles tab.
Click New.
Enter the profile name: synchronous.storefront.profile
Enter the number of milliseconds for the client connection timeout: 1,000
Select Enable Circuit Breaker and enter the number of calls that must fail to trigger the circuit breaker.
Select Enable Rate Limit and enter the maximum number of calls that B2C Commerce makes for the rate limit interval.