algorithmiaio/dev-center

API endpoint, docs and git endpoint are hardcoded pretty much everywhere

Opened this issue · 5 comments

pmcq commented

Since docs are hosted, on-premise deployments will end up viewing docs that show to curl https://api.algorithmia.com instead of the appropriate endpoint

pmcq commented

FWIW looks like the following pages are impacted, some of which use http instead of https so it'd be nice to fix both of those at the same time

_pages/clients/perl.md
_pages/clients/net_c_sharp.md  # References api.algorithmia.com as  a default so not actually impacted
_pages/clients/alexa.md
_pages/clients/curl.md
_pages/clients/php.md
_pages/getting-started.md
pmcq commented

Actually this is way broader than that... there's links e.g. in the scala algorithm developer guide that link to the public website's scala client. Some guides (e.g. python) do link correctly by using {{ site.baseurl }}
https://github.com/algorithmiaio/dev-center/blame/487b51314b7763419d9f763415c456ef085a8463/_pages/algorithm-development/languages/python.md#L41
vs
https://github.com/algorithmiaio/dev-center/blame/290f8c2d00c08b789374b35b25db5d98084e24d7/_pages/algorithm-development/languages/scala.md#L20

Overall the docs refer to:

algorithmia.com
api.algorithmia.com
blog.algorithmia.com
developers.algorithmia.com
docs.algorithmia.com
git.algorithmia.com
pmcq commented

Suggestion:

  • Change references to developers.algorithmia.com to algorithmia.com/developers equivalent
  • Change all fully qualified links like https://algorithmia.com/developers/clients/scala to be relative links
  • Change algorithmia.com to WEB_SERVER to be templated by the frontend
  • Change git.algorithmia.com to GIT_SERVER to be templated by the frontend
  • Change api.algorithmia.com to API_SERVER to be templated by the frontend
  • Leave blog.algorithmia.com as pointing to public blog, results in broken links from no-internet environments but non-critical
  • Leave docs.algorithmia.com as pointing to public slate docs, results in broken links from no-internet environments, but while it's definitely nice to have it's non-critical for people to have the full API spec since there are guides per algorithm language anyway. If someone is trying to generate a new algorithmia client in a non-internet environment... they might not have a great time, but it's not critical
  • 👍1
peckjon commented

@anowell are WEB_SERVER / GIT_SERVER / API_SERVER already available? If not, can you add before we being hacking on this?

anowell commented

They are not. The web-server implementation is pretty straight forward (see here). For the interest of making links kinda still work during local development without running a web-server locally, I want to propose alternatives to a few of @pmcq's suggestions.

Instead of using WEB_SERVER, GIT_SERVER, and API_SERVER, can we just have the web-server replace:

  • https://algorithmia.com with Const.webServer
  • https://api.algorithmia.com with s"https://${Const.apiServer}"
  • https://git.algorithmia.com with s"https://${Const.gitServer}"

Also, we still need to figure out how to make certain pages not even appear in an enterprise build of the dev-center. For example, all the FAQ around pricing shouldn't exist at all.