Convo: api.kanka.io

[ilestis]

Hey, @eXaminator I've been thinking on some API changes for Kanka and figured it would make more sense to have it out in the open, as this plugin is the biggest user of the Kanka API ;-)

For the next Kanka update, I want to introduce a new api.kanka.io domain that will replace kanka.io/api. Behind the hood, all the endpoints will be exactly the same, but use a new domain and url, moving the api part of the url from a folder path to a subdomain.

For example, this means that the https://kanka.io/api/1.0/campaigns endpoint would now be https://api.kanka.io/1.0/campaigns.

Obviously just breaking all the API isn't an option . I have two solution in mind, but you might have some others.

Option 1

Keep all the endpoint still working for a few months, allowing you to update the project to use the new url, and give people time to update their plugins.

Pros

• No disruption for end users
• Fallback if something is broken with the new API

Cons

• Makes the code on my end very messy and slower overall
• Changes to the API will only be on the new subdomain

Option 2

All requests to https://kanka.io/api/* get a 301 redirect to https://api.kanka.io/

Pros

• Easy to implement on my end, simplifying the code

Cons

• fetch() needs to be set up to not only follow redirects, but also forward headers to the redirect, which I suspect is off by default for obvious security reasons.

So, where does that leave us? I don't believe that option 2 is viable and would put too much stress on your end, so I am looking into implementing option 1.

This brings me to the following questions.

• Once the new API is available, is it easy for you to change the base config to use it? I know you recently allowed changing the API url for people who self-host Kanka.
• This will still require more than just changing the url, as the api/ part is dropped from the path. Looking at the code, it seems to my untrained eye that it's added in the same place, but would also require adapting https://github.com/eXaminator/kanka-foundry/blob/bd0d0d817328a004667dafc80884b2fcd6f237ee/src/api/KankaFetcher.ts#L81C1-L81C1
• Do you think that you will have time before the end of the year to adapt the plugin? I imagine turning off the old routes in January 2024, which will hopefully allow enough time for everyone to switch and update to the new urls.

Sorry for the long text 🙈

[eXaminator]

Hey, thanks for the heads up!

As the domain is configurable, I would need to add a migration that checks if the user has the default configured which is then updated (not a big deal). I would also have to remove the /api path from the url (also not a big deal).

That being said: How will this change affect self hosted instances? Will they keep the /api path? Or are they expected to host the api under a custom subdomain too?

I'll have to dig into fetch and how it handles redirects across different domains, but at least according to mdn it should redirect automatically. But I agree that the Authorization header is less obvious to me right now.

That being said, I would actually prefer the 301 from a purely technical standpoint, as it communicates (to some degree) that the old API is deprecated and people should move to the new one. But it would obvsiouly break more stuff (including this module for people who have not updated to a newer version that properly handles the 302, should it actually to be a problem).

So let me check this out a little bit more and let me come back to you on this thread.

Regarding the timeframe, that should not be a problem at all. The changes - whatever they are - should be minor on my end. So once I know if self hosted instances need special handling and how fetch actually behaves in this situation (I might need to check different browsers though), I'll probably be able to release a patch relatively quick.

Luckily, this module is still compatible with Foundry VTT 10, something that might change sometime this year due to some changes I have been working on (on and off), so a patch should reach most people, even those who have not yet updated to the latest Foundry release.

[ilestis]

Awesome! All around great news.

Regarding self-hosted, it will still be the old urls on their-kanka-url.net/api/1.0. At the moment the code is still in the same repo, however the long term goal is to split the API code from the Kanka app itself (we are looking into having a frontend, backend, and api repo in the future). In the future, for people who self-host, it might be an extra docker image with its own unique port rather than a subdomain, but that's not something tjat will happen this year. The new subdomain is only for kanka.io right now to make it seamless the day I switch to a separate codebase.

I can set up the 301 redirects on Kanka's QA server so we can do tests there if that sounds good :)

[eXaminator]

I'm thinking about having people add the /api path to the configured URL (and add it automatically via migration), that way it's independent whether it's SaaS or self-hosted.

Testing this on the QA server might be a great way to see what works and what doesn't in a way that's close to the real thing. Just let me know once the changes have been made and deployed on that server (and give me some info on how to access that) and I'll see that I can check everything out and hopefully make the neccessary changes. :)

[Spazbit]

Sorry for the interrupt, but have been attempting to get the Kanka Module imported on foundry. Not sure if the adjustments here have anything to do with my lack of success or if its just user error [ likely the latter ]

I keep getting the error "There was an error fetching data from Kanka. Check settings and try again." Im working on a newly created API token, but for whatever reason it wont accept it.

Also wondering if this is due to which URL setup I'm attempting since I see above the mention to change it from;

For example, this means that the https://kanka.io/api/1.0/campaigns endpoint would now be https://api.kanka.io/1.0/campaigns.

Please Advise at your convenience.

[ilestis]

@Spazbit not related, as the changes discussed here are just ideas for the future. No work has been done yet :)

[ilestis]

As hinted at in Discord, here is a summary of what the changes will look like.

In October, Kanka will be split into 3 apps, each with their own URL and routing system.

kanka.io

This will be just the frontend, will contain 0 user login, and won't be hosted by me, but distributed in the cloud "on the edge". Campaign urls like https://kanka.io/en-US/campaign/123 will be automatically redirected to the new backend.

app.kanka.io

This is now where the Kanka application lives, where users log in and interact with their campaigns. Note that we are removing the language qualifier from URLs, and replacing campaign/ with something else which we are still debating. At the moment it's a placeholder w/. Premium campaigns will no longer use a campaign id in the url, but a "slug".

For example, if a campaign today is at https://kanka.io/en-US/campaign/123, starting october it will be https://app.kanka.io/w/here-be-dragons

api.kanka.io

This is the new API (which code wise is exactly the same today. Where today you call https://kanka.io/api/1.0/campaigns, in october it will need to call https://api.kanka.io/1.0/campaigns.

In the API, campaigns will now expose their "slug", but routing will still use the unique ID.

API changes

• The biggest change is moving the api/ part of the route to the new subdomain.
• I'm removing the language header since it is no longer needed.
• The entity "view urls"property points to the new urls.
• Mentions also point to the correct new urls.

Everything else at this point in time does not change. People who self-host probably won't want to set up multiple subdomains and keep everything as it currently is, which the code supports (minus dropping the language parameter from all urls)

Changes mentioned that didn't end up happening

I didn't end up putting a redirect in place, but it's something I can still add if you see it being valuable. I do however get charged for redirects so I could prefer to not have to keep it up more than a few weeks :P

Testing

You can test the new APIs at the following url

https://qa-api.kanka.io

So for example, to get a list of entities in a campaign

https://qa-api.kanka.io/campaigns/1

I'll send you an API key privately to test it out.

[eXaminator]

Since the deployment of Kanka 2.0 went through I mark this as closed as I'm sure bugs will flow in through new issues or discord ;)