docs: add guidance on connecting to a remote API host

[danwatford]

Depends on #578

[manekinekko]

can't we set this automatically by the cli, or ignore it if the user is connecting to a remote address?

[danwatford]

We can do. At the time I wanted to keep changes to a minimum in case their was some cases I hadn't realised.

[danwatford]

Actually after testing some other swa-cli bits I realised that specifying an api-devserver-url option is not necessary. I think the bit that confused me was following in cli/commands/start.ts which suggested api-location would be ignored if it didn't resolve to file location, but it was still necessary to specify api-location in order to get apiDevServerUrl checked.

static-web-apps-cli/src/cli/commands/start.ts

Lines 186 to 201 in 19c619b

	if (apiLocation) {
	// resolves to the absolute path of the apiLocation
	let resolvedApiLocation = path.resolve(apiLocation);
	if (apiDevserverUrl) {
	// TODO: properly refactor this after GA to send apiDevserverUrl to the server
	useApiDevServer = apiDevserverUrl;
	apiLocation = apiDevserverUrl;
	}
	// make sure api folder exists
	else if (fs.existsSync(resolvedApiLocation)) {
	apiLocation = resolvedApiLocation;
	} else {
	logger.info(`Skipping API because folder "${resolvedApiLocation}" is missing`, "swa");
	}
	}

I now realise that even though a line about the api-location being missing was logged, the api-location was still passed to msha/server so was still accepted.

I'll clean up the example and api-devserver-url option documentation.

What usecases is the api-devserver-url option needed for?