Fast Path to B2C Commerce

Developer Certification

Module 6: OCAPI and

Service Framework
Module 6.1: Open Commerce API (OCAPI)

• Objective - By the end of this module you will be able to a use an OCAPI resource to
retrieve Custom Objects from a site
• This module will cover:
• OCAPI basics
• OCAPI resource setup
• Using Postman to authorize against a SB and retrieve COs
• What is this functionality and why does it matter for implementations?
• OCAPI is the current API available for realtime access by 3rd party systems
• OCAPI allows front-end applications written in other languages to access the B2C
Commerce data
• Postman is a useful tool to test your OCAPI configuration and performance
What is OCAPI?
AKA Open Commerce APIs
RESTful API that consists of three components APIs:
● Shop API – used for storefront-like interactions (e.g. from a mobile app)
● Data API – used for server-to-server integrations (e.g. OMS pushing order status)
● Meta API – used for getting information about the available OCAPI resources
Sample usages of OCAPI APIs
Using Shop API:
● Endless Aisle
● Customer Service Center
● Pinterest Buyable Pins
● Mobile shopping applications
● OCAPI Explorer (all APIs)
Using Data APIs:
● Business Manager
● CMS/ERP/PIM/CRM/etc. server-to-server
integrations
● Continuous Integration
● OCAPI Explorer (all APIs)
OCAPI Resources Documentation

Shop API resources

https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp
/OCAPI/current/shop/Resources/index.html
Data API resources
https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp
/OCAPI/current/data/Resources/index.html
Each resource is documented with method, request and response document formats
Special Data API resources (system jobs – useful for CI implementations)
https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp
/OCAPI/current/usage/SystemJobs.html
HTTP Methods available

1. GET (s) – retrieve resource data

2. HEAD (s) – returns headers only (same as GET request), but not resource data
3. DELETE (i) – remove existing resource(s)
4. PUT (i) – create, update or replace a resource (not available on PRD and STG instances)
5. PATCH – partial resource update (unlike PUT touches only what is provided as data)
6. POST – create new resource with id provided from the server, override an HTTP method,
execute special actions like password reset requests
7. OPTIONS (s) – return list of available operations for a resource (in header "Allow")
OCAPI Settings

Control OCAPI client id permissions and also the caching of various OCAPI resources.
Done from Administration > Site Development > Open Commerce API Settings
The settings start with JSON document format version identifier, it is the format of the
configuration, it does NOT limit the calls to that specific version.
More information about the configuration is available in:
https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp
/OCAPI/current/usage/OCAPISettings.html
It is possible to limit the resource properties visible for a particular client:
https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp
/OCAPI/current/usage/PropertySelection.html
Client ID

Client ID is needed for all OCAPI calls and is configured in Account Manager
https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp
/AccountManager/AccountManagerAddAPIClientID.html
Once client ID is configured and enabled in Account Manager, it is needed to do corresponding
configuration about resource-level access that this client id will have to various OCAPI resources.
Such configuration is also needed on your sandboxes: use the 30 a’s client id in your settings:
"client_id":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
Using Postman as a tool to learn OCAPI

● It is a free product, extensively

used in the industry
● Postman allows you to share
configurations as well as test
calls with others in your team
OCAPI Explorer (aka API Explorer)
This is a B2C Commerce proprietary tool

● Currently works on Firefox, not on Chrome

● Make sure that your account manager user
has the Documentation User role
● Navigate to
https://api-explorer.commercecloud.salesforce.com
● Change the URL to your sandbox instance
● Authorize using the 30 a’s from your client
id (both user and pwd)
● Click Dismiss on the authorization popup
● Click Explore to see the APIs available
Module 6.1 Demo: Use OCAPI to get COs for a given site

1. We will visit the BM OCAPI settings for

a. Data API with Global scope
b. Settings for searching custom objects
2. Check the client id
3. Add a new resource to the Data API, Global OCAPI settings:
a. resource: /custom_objects_search/*
b. method = POST
c. Allow read and write
4. Visit documentation to find a data API for getting custom objects
5. In Postman, run the custom_object_search to get all RefArch
NewsletterSubscription COs
Import this collection and enviroment in postman to recreate this demo.
Module 6.1 Homework: Implementing Shopping Scenarios
This is how real headless applications do it!

1. One of great architects, Abraham David Lloyd, has implemented a very

real OCAPI scenarios for conversational commerce.
2. They demonstrate how to implement guided shopping use-cases --
where a customer's basket can be interacted with via an agent (ex. the
agent adds products and applies discounts).
3. Import this collection into Postman.
4. Import this environment template into Postman.
5. Read the documentation on the first gist.
6. Setup environment: you only got a template, not real values!
7. Get after it!
Module 6.2: Web Services Framework

• Objective - By the end of this module you will be able to a understand the Web
Services Framework
• This module will cover:
• Web service basics
• Configuration in Business Manager
• Coding your web service
• Why does this functionality matter for implementations?
• Web services are required to connect to 3rd party systems (i.e. payment)
• By using the framework, you can take advantage of pre-built throttling and
monitoring capabilities
What is the Web Services Framework?
AKA Services

B2C Commerce provides a web service framework to make it easier to manage RESTful and
SOAP calls to 3rd party systems.
The framework helps you:
● Manage calls to web services
● Analyze service performance by collecting analytics on your web service calls
The framework enforces limits that you configure:
● Limits on the overall number of calls allowed in a time interval
● Limits on the number of failed calls allowed in a time interval
Steps to set up a Web Service

1. Configure Service in Business Manager

2. Code your web service
3. Set up logging and troubleshooting your web service
4. Get the web service ready to go live
5. Invoke the web service from:
a. A controller that makes a decision based on a service response
b. A model that needs to get data from a service before it can be used on a view
c. A custom job step that needs to interact with a 3rd party service
There is extensive documentation for this but unfortunately is not written with SFRA controllers in
mind. It still refers to .ds files. The main concepts are still demonstrated.
Configure Service in Business Manager
Navigate to Administration > Operations > Services to create a new service

Every service configuration needs a profile and

credentials, so you have to configure those before you
can save the service!
Configure Service Profile in Business Manager
Navigate to Administration > Operations > Services > Profiles tab

The profile specifies if you want to enable timeout, circuit breaker, and rate limit on the service.
Great explanation of breaker and rate limit here.
Configure Service Credential in Business Manager
Navigate to Administration > Operations > Services > Credentials tab

These settings specify the endpoint, username and password to connect to the service.
Also, any custom attributes required for the connection can be specified here.
Code your web service

1. Invoke the LocalServiceRegistry.createService() method

2. Implement a minimum of 3 functions inside the method. Stydy ServiceCallback to understand
the significance of each callback method:
a. mockCall: called when the service is in Mocked mode. None of the following methods will execute.
b. createRequest: called when the service in Live mode. Configures the actual request.
c. parseResponse: parses the actual object returned by the service
3. Make the call to the service:
a. service.call(object), where object is the one created by the createRequest callback above.
b. Handle and log errors as appropriate.
Module 6.2 Demo: Examine a Web Service Implementation

1. We will go thru the example used in the documentation:

https://xchange.demandware.com/docs/DOC-20384
2. Download it locally
3. Locate the HTTP service function implementation
4. Look at the service registration
5. Locate the callback methods
6. Look at the service call
Module 6.2 Homework: Implementing an SFRA web service
Great way to practice creating a controller, a script, and a job!

1. Create an SFRA version of the HTTP web service code reviewed during the demo.
2. Create a new job with a custom step that calls your new SFRA web service. Remember
to:
a. Create steptypes.json in the cartridge
b. Create a custom script
c. Create job that uses this custom script
3. Test the web service in Mocked mode.
4. Create a pull request in the sfra_demo repo
5. We will review and accept your PR.