Feat: support custom APIs @W-15111169@ #149

joeluong-sfcc · 2024-04-16T22:09:26Z

This PR adds support for custom APIs by exposing a helper function called callCustomEndpoint that allows users to call their custom API following common SDK patterns. This PR also pulls out some of the reused logic in operations.ts.hbs for fetching data and puts into a helper function called doFetch.

Some features of the callCustomEndpoint helper:

Defaults apiVersion to v1 if not provided
Defaults content-type header to application/json if not provided

Below is a sample script I used for testing the callCustomEndpoint helper function. Reach out to me for instructions on how to run this with the proper credentials.

import pkg from 'commerce-sdk-isomorphic';
const { helpers } = pkg;

// replace client credentials
const CLIENT_ID = "clientId";
const ORG_ID = "orgId";
const SHORT_CODE = "shortCode";
const SITE_ID = "siteId";

// client configuration parameters
const clientConfig = {
  parameters: {
    clientId: CLIENT_ID,
    organizationId: ORG_ID,
    shortCode: SHORT_CODE,
    siteId: SITE_ID,
    endpointPath: 'greeting',
    apiName: 'e2e-tests',
    apiVersion: 'v1',
  },
  // proxy: 'http://localhost:8888/mobify/proxy/api'
  // baseUri: 'https://{shortCode}.alternativeBaseUri.com/custom/{apiName}/{apiVersion}'
};

const access_token = "<INSERT_ACCESS_TOKEN>"

let response = await helpers.callCustomEndpoint({
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        authorization: `Bearer ${access_token}`
    }
}, clientConfig, false)

console.log('RESPONSE: ', response)

Resulting fetch request URLs:

No proxy/baseUri: https://shortcode.api.commercecloud.salesforce.com/custom/e2e-tests/v1/organizations/orgId/greeting?siteId=siteId
With Proxy: http://localhost:8888/mobify/proxy/api/custom/e2e-tests/v1/organizations/orgId/greeting?siteId=siteId
With baseUri: https://shortcode.alternativebaseuri.com/custom/e2e-tests/v1/organizations/orgId/greeting?siteId=siteId

src/static/helpers/fetchHelper.ts

bendvc · 2024-04-22T22:11:47Z

templates/operations.ts.hbs

-        headers,
-        method: "{{loud method}}"
-      };
+      const response = await runFetchHelper(


Were their any measurable change in the side of a generated lib before and after with this change. Looks like we are only saving 2 lines roughly per use of this template, but it might add up.

yarn run check:size for main branch:

PASS lib/index.cjs.js: 44.84KB < maxSize 45KB (gzip) PASS lib/index.esm.js: 44.73KB < maxSize 45KB (gzip) PASS commerce-sdk-isomorphic-with-deps.tgz: 337.06KB < maxSize 350KB (gzip)

yarn run check:size for ju/custom-endpoint branch:

PASS lib/index.cjs.js: 44.13KB < maxSize 45KB (gzip) PASS lib/index.esm.js: 44.02KB < maxSize 45KB (gzip) PASS commerce-sdk-isomorphic-with-deps.tgz: 337.43KB < maxSize 350KB (gzip)

Seems like lib/index.cjs.js and lib/index.esm.js have decreased slightly, but commerce-sdk-isomorphic-with-deps.tgz has increased slightly 😮

src/static/helpers/fetchHelper.test.ts

CHANGELOG.md

src/static/helpers/fetchHelper.ts

src/static/helpers/customApi.test.ts

CHANGELOG.md

README.md

src/static/helpers/customApi.ts

johnboxall · 2024-04-24T19:58:31Z

README.md

+    endpointPath: 'customers',
+    apiName: 'loyalty-info',
+    apiVersion: 'v1', // defaults to v1 if not provided


clientConfig normally contains a static values – clientId|organizationId|shortCode|siteId – these things rarely if ever change between calls in regular implementations.

endpointPath|apiName|apiVersion are likely to change.

Would you consider moving these values into the options of the request? At least to me, if feels more natural to have them there with other options that usually vary call to call.

Added a new property to options called customApiPathParameters

customApiPathParameters?: { apiName?: string; apiVersion?: string; endpointPath?: string; organizationId?: string; shortCode?: string; };

path parameters can now be passed either in options.customApiPathParameters or clientConfig.parameters.

johnboxall · 2024-04-24T20:00:01Z

README.md

+const rawResponse = false;
+const accessToken = '<INSERT ACCESS TOKEN HERE>';
+
+let response = await helpers.callCustomEndpoint(


I don't feel strongly, but would you consider an alternative argument structure for callCustomEndpoint?

await helpers.callCustomEndpoint({ options: myOptions, clientConfig: myClientConfig, rawResponse: true })

This interface makes it much more clear to folks using regular old JavaScript what the impact of the three arguments will be.

It would also allow you to significantly shrink this code example:

await helpers.callCustomEndpoint({ options: { method: "GET", parameters: { queryParameter: "queryParameter1", siteId: SITE_ID, }, headers: { "Content-Type": "application/json", authorization: `Bearer <your-access-token>`, }, }, clientConfig: { clientId: "<your-client-id>", organizationId: "<your-org-id>", shortCode: "<your-short-code>", siteId: "<your-site-id>", // Custom API path parameters endpointPath: "customers", apiName: "loyalty-info", apiVersion: "v1", // defaults to v1 if not provided }, rawResponse: true, });

Would you also consider showing an example of a mutation request eg. a POST where you pass a request body?

Updated argument structure to be a single argument, following the pattern provided above:

await helpers.callCustomEndpoint({ options: myOptions, clientConfig: myClientConfig, rawResponse: true })

and updated README example to reflect this new change and provide a mutation request example

johnboxall · 2024-04-24T20:01:51Z

README.md

+      siteId: SITE_ID,
+    },
+    headers: {
+      'Content-Type': 'application/json',


Do we expect callers to pass the content type or can it be automatically inferred or default to JSON?

Updated implementation to default to "Content-Type" : "application/json" if Content-Type header is not provided

README.md

src/static/helpers/customApi.ts

…ions

johnboxall

@joeluong-sfcc – the updated interface looks good. I've only reviewed the README, I'll let the rest up to others.

README.md

johnboxall · 2024-04-25T23:17:52Z

README.md

+const CLIENT_ID = "<your-client-id>";
+const ORG_ID = "<your-org-id>";
+const SHORT_CODE = "<your-short-code>";
+const SITE_ID = "<your-site-id>";
+
+// client configuration parameters
+const clientConfigExample = {
+  parameters: {
+    clientId: CLIENT_ID,
+    organizationId: ORG_ID,
+    shortCode: SHORT_CODE,
+    siteId: SITE_ID,
+  }
+};


I don't feel strongly, but you're repeating yourself here:

Suggested change

const CLIENT_ID = "<your-client-id>";

const ORG_ID = "<your-org-id>";

const SHORT_CODE = "<your-short-code>";

const SITE_ID = "<your-site-id>";

// client configuration parameters

const clientConfigExample = {

parameters: {

clientId: CLIENT_ID,

organizationId: ORG_ID,

shortCode: SHORT_CODE,

siteId: SITE_ID,

}

};

const clientConfigExample = {

parameters: {

clientId: <your-client-id>,

organizationId: "<your-org-id>",

shortCode: "<your-short-code>",

siteId: "<your-site-id>",

}

};

Also, because you've chosen meaningful variable names, you don't really need the code comment.

Why do you pass siteId as a param to the client Config and then pass it again as a parameter later?

That was a miss where I didn't use the siteId from the clientConfig, code has been updated to use siteId as query parameter if available

src/static/helpers/customApi.ts

bendvc · 2024-04-29T15:56:56Z

src/static/helpers/customApi.ts

+    pathParams.apiVersion = 'v1';
+  }
+
+  const defaultBaseUri =


We previously talked about this decision on hard coding prod uri.. are we cool with that. Have we documented it anywhere?

It's the default base URI if you don't provide one yourself. You can override this behavior by passing in your own baseUri in the clientConfig

const clientConfig = { parameters: { ... }, baseUri: 'https://{shortCode}.alternativeBaseUri.com/custom/{apiName}/{apiVersion}' };

Behavior is documented in the tsdoc comments. When we release and run the generate doc command it'll populate the static docs site:

* @param args.clientConfig.baseUri? - baseUri used for the request, where the path parameters are wrapped in curly braces. Default value is 'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}'

I guess my question is, and I think I know the answer. But if you were to generate a client where the raml specifies the base url a something like 'https://{shortCode}.dev-api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}' notice the "dev" in "dev-api" all calls to the apis will goto that url. but if I make a custom api call without passing that "dev" value, it will make it to production. Correct?

Yes, because the callCustomEndpoint helper function does not interact with any type of RAML, it'll use the production URI as default if you don't provide a base URI.

@bendvc I think you are right. Unless the user overrides baseUri it will always go to the default. @joeluong-sfcc Can we read the default value from a config file instead of hard-coding so that it is easy to change the default value

May be we shouldn't have default URI. How about just throwing an error if the baseUri is not provided?

Moved the default base URI into a config file. I think it still makes sense to have a default URI as all the other APIs use the production URI as default, but I've made it more clear in the README example on how to pass it into the function. Does that work for y'all @unandyala @bendvc?

bendvc · 2024-04-29T16:25:14Z

templates/operations.ts.hbs

-        }
-      {{/unless}}
+      {{else}}
+      return response as Response | {{getReturnTypeFromOperation this}};


Can you explain this line a little bit more for me. If we are expecting that we aren't using a rawResponse we are saying that the return value is the union of a Response object and the return type of this operation? Why wouldn't it simply be the return type of the operation without the union?

We use the rawResponse when we call the doFetch helper function for the response variable. Since we don't know what rawResponse is when we pass it to doFetch, the result is either a response object OR the return type as doFetch will either return a raw response object or the return type

I think it is to handle any unexpected response - the response that is not defined in RAML specially in case of error response

unandyala

LGTM

joeluong-sfcc added 10 commits April 15, 2024 16:02

add custom endpoint helper

c347cdb

refactor

f640715

implement runFetchHelper

5422ecb

use runFetchHelper in operations handlebar template

e14fa98

fix broken calls

afe02d3

fix linting errors and most type errors

b570a91

Refactor and add tsdoc comments

fef40ae

refactor and add unit test

04e4ae1

add comment for test coverage

dd26eae

add unit test and update changelog

55afa1d

joeluong-sfcc changed the title ~~Feat: support custom endpoints @W-15111169@~~ Feat: support custom APIs @W-15111169@ Apr 19, 2024

joeluong-sfcc marked this pull request as ready for review April 19, 2024 20:54

joeluong-sfcc requested a review from a team as a code owner April 19, 2024 20:54

update type for body

2ee3c0e

bendvc reviewed Apr 22, 2024

View reviewed changes

src/static/helpers/fetchHelper.ts Outdated Show resolved Hide resolved

bendvc reviewed Apr 22, 2024

View reviewed changes

src/static/helpers/fetchHelper.test.ts Outdated Show resolved Hide resolved

bendvc reviewed Apr 22, 2024

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

joeluong-sfcc added 2 commits April 23, 2024 10:10

address PR comments

b646330

add example in README

48dcd28

unandyala reviewed Apr 23, 2024

View reviewed changes

src/static/helpers/fetchHelper.ts Outdated Show resolved Hide resolved

joeluong-sfcc added 2 commits April 24, 2024 09:04

update types and allow baseUri as argument

ef6033a

lint

d73dfab

unandyala previously approved these changes Apr 24, 2024

View reviewed changes

src/static/helpers/customApi.test.ts Show resolved Hide resolved

add check in test for response status code

237e7cc

joeluong-sfcc dismissed unandyala’s stale review via 237e7cc April 24, 2024 17:45

unandyala previously approved these changes Apr 24, 2024

View reviewed changes

johnboxall reviewed Apr 24, 2024

View reviewed changes

combine params into 1 object and pull out custom path params into opt…

f7ab768

…ions

joeluong-sfcc dismissed unandyala’s stale review via f7ab768 April 24, 2024 23:02

joeluong-sfcc added 3 commits April 25, 2024 12:34

default application/json as content type and add test

944a273

add check for clientConfig headers

0b0e5fb

lint

efc1863

johnboxall reviewed Apr 25, 2024

View reviewed changes

joeluong-sfcc added 3 commits April 29, 2024 10:34

use siteId from clientConfig

3522f36

update README

88f58f5

remove comment

c9579bd

bendvc reviewed Apr 29, 2024

View reviewed changes

src/static/helpers/customApi.ts Show resolved Hide resolved

bendvc reviewed Apr 29, 2024

View reviewed changes

pull out default base URI into config file

5fb1e17

unandyala approved these changes Apr 29, 2024

View reviewed changes

bendvc approved these changes Apr 30, 2024

View reviewed changes

joeluong-sfcc merged commit 93358e3 into main Apr 30, 2024
10 checks passed

kevinxh mentioned this pull request May 3, 2024

Feat: Add support for custom APIs @W-15585881@ SalesforceCommerceCloud/commerce-sdk#402

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat: support custom APIs @W-15111169@ #149

Feat: support custom APIs @W-15111169@ #149

joeluong-sfcc commented Apr 16, 2024 •

edited

Loading

bendvc Apr 22, 2024

joeluong-sfcc Apr 23, 2024

johnboxall Apr 24, 2024

joeluong-sfcc Apr 25, 2024

johnboxall Apr 24, 2024

johnboxall Apr 24, 2024

joeluong-sfcc Apr 25, 2024

johnboxall Apr 24, 2024

joeluong-sfcc Apr 25, 2024

johnboxall left a comment

johnboxall Apr 25, 2024

joeluong-sfcc Apr 29, 2024

bendvc Apr 29, 2024

joeluong-sfcc Apr 29, 2024

bendvc Apr 29, 2024

joeluong-sfcc Apr 29, 2024

unandyala Apr 29, 2024

unandyala Apr 29, 2024

joeluong-sfcc Apr 29, 2024

bendvc Apr 29, 2024

joeluong-sfcc Apr 29, 2024 •

edited

Loading

unandyala Apr 29, 2024

unandyala left a comment

Feat: support custom APIs @W-15111169@ #149

Feat: support custom APIs @W-15111169@ #149

Conversation

joeluong-sfcc commented Apr 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnboxall left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joeluong-sfcc Apr 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

unandyala left a comment

Choose a reason for hiding this comment

joeluong-sfcc commented Apr 16, 2024 •

edited

Loading

joeluong-sfcc Apr 29, 2024 •

edited

Loading