Less restrictive `new GhostAdminApi()` arguments about sdk HOT 9 CLOSED

With the current SDK design I found that ambiguous. There are arguments for host and ghostPath - in the case of a sub-directory install which argument should the subdirectory path element be added to?

Good questions.

ghostPath is a stopgap solution for us having hardcoded /ghost/ in the SDK, so that in future when this does become customisable, it's an extra config option already. It's not documented in the Content SDK: https://docs.ghost.org/api/javascript/.

host should be your admin URL including any subdirectory, although perhaps host wasn't the best name 🤔

This does me back to my previous suggestion about having host listed on the integration screen, to make it absolutely clear what to paste into this field cc @peterzimon

from sdk.

This does me back to my previous suggestion about having host listed on the integration screen, to make it absolutely clear what to paste into this field cc @peterzimon

If we do this then we can update the Zapier auth screen too so it has an "API Host" field rather than "Admin URL", seems like that will be more future-proof too.

@peterzimon it's worth noting that the Ghost Admin changes would need to be made in two places, the Custom Integration and the Zapier screen.

Custom Integration screen:

• add Admin API Key field (currently behind experiments flag)
• add Admin API URL field

Zapier Integration screen:

• add Admin API Key field
• add Admin API URL field

"Admin API URL" or "API Host" naming is not decided 🙂

Within Zapier's own "Connect Account" screen we can use the same field names so that it's really obvious that you copy the contents of each field across.

from sdk.

We don't currently do this for the content API, leaning towards throwing errors until the correct URL is provided.

The reasoning behind this, is that people interacting with our SDK tools are developers, and developers have a better experience when they understand what's happening beneath them. E.g. tell them to enter https, don't magically change http to https without them knowing.

Zapier is a very interesting client example, because in this case, Kevin is the developer of a shared client, and people interacting with the shared client (Zapier) are users. Users have significantly less tolerance for errors as well as less interest in what's happening under the hood, so for users, magic is more desirable.

This is always a fine balance to tread.

In this case, I think at least right now, that it makes sense that Kevin as the developer of a client for non developer users has to handle some extra logic, but:

• Are we able to validate the URL in Zapier at all? E.g. to ensure we're handed HTTPS.
• ghostPath is currently not editable, so I don't think you have to account for that right now.

The slash / no slash is the one thing where maybe we should handle it in the admin-api tool, cos it's something most people don't notice. It's an implementation detail of Ghost, not an important distinction like the fact that admin URLs must be https.

from sdk.

Users have significantly less tolerance for errors as well as less interest in what's happening under the hood, so for users, magic is more desirable.

👍 agreed. Good point on the desired audience for each tool.

• Are we able to validate the URL in Zapier at all? E.g. to ensure we're handed HTTPS.

Yes, that's doable 👍

• ghostPath is currently not editable, so I don't think you have to account for that right now.

With the current SDK design I found that ambiguous. There are arguments for host and ghostPath - in the case of a sub-directory install which argument should the subdirectory path element be added to? The strict leading/trailing slash complicates this because if you have a sub-directory install I think it's common to say your "host" would be https://mysite.com/blog/ rather than https://mysite.com/blog (I was actually tripped up by this and took the ghostPath to be the full path to ghost incl. the subdir so used that argument instead of appending the non-trailing-slash subdir onto host)

from sdk.

I think if we expose an "Content/Admin API URL" in the in the integrations screen we can also simplify the SDK arguments so that only a URL is passed in.

new GhostAdminAPI({url: 'https://mysite.com/ghost/api/', version: 'v2', key: 'xxx'}). I don't see why the ghostPath argument is necessary, it seems like it's an internal implementation detail that even developers shouldn't need to care about, if it's only about validation then we can do that just as easily with a URL without needing to make the arguments more confusing.

If a URL can be provided then it's also future-proof as it allows for any part of the URL to be changed if it's configurable later on, eg. I have my API configured to live at https://api.mysite.com/ 🤔 but my "admin" SPA lives on https://admin.mysite.com.

from sdk.

@kevinansfield
Here's how we should change the custom integration screen in Ghost Admin.

Notes:

• "Copy" button appears only on row hover (similarly to current version)
• "Copied to clipboard" should flash temporarily instead of the key/URL value in the given row
• we can reuse the same design for the Zapier integration screen and extend it with a little help to bring attention that these values will be needed on Zapier connect

from sdk.

Should we maybe add url to both the content and admin sdk, and deprecate host - remove it from docs, have it work for now, remove it whenever we have a good moment?

from sdk.

@kevinansfield What is the state of this issue? Is it done?

from sdk.

The UI side of things in Ghost-Admin is done. @ErisDS's suggestion for swapping host (with deprecation) for url sounds good, I'll confirm and implement.

from sdk.