Remove '/api' from URLs
Closed this issue · 10 comments
If we plan on hosting the API at api.pokeapi.co (as per pokeapi#355), shouldn't the API URL be like api.pokeapi.co/v2/ability/1 rather than api.pokeapi.co/api/v2/ability/1? Having the api in there twice seems redundant.
That's totally doable, but I'm not sure what the purpose of a separate subdomain is. Why support two different URLs to the same content and try to have people migrate to the new one, when we can simply continue to support the one we already have?
Because the website and the API are two separate projects, and the discussion in pokeapi#355 seemed to indicate that merging the two projects for deployment added a lot of complexity. Also, keeping them on separate domains allows them to be updated separately.
As far as which URL should be canonical, @tdmalone suggested that the proxy might decrease performance slightly, so it might be better to change the canonical URL to api.pokeapi.co. But the performance hit might be negligible, in which case the canonical URL can stay as pokeapi.co/api and the fact that the API is hosted at a separate domain becomes an implementation detail.
Also, if we did change the canonical URL, we wouldn't need to try to have current users migrate over, just new users. From a technical standpoint, supporting both URLs shouldn't be a problem because Netlify can handle the proxy for us.
I would stay with the classic pattern. pokeapi.co/api/v2 this was the pattern used till now. I don't see any point in changing it. Moreover the migration process could take forever. Let's remember that still a large part of users is using the v1, so they didn't migrate at all.
@Naramsim Then how do we address the points raised in #355? Namely, keeping the two projects separate (and separately updatable) and being able to merge them together at build time without tons of complexity.
Also, there would not be a migration process; both URLs would be supported indefinitely, so we would not need to push users to the new URL. Either way, it doesn't really matter to me, but the more we discuss this, the more I see how supporting two URLs might be unnecessarily redundant, even if it's the simplest solution.
I'm not seeing how we gain any simplicity by supporting both URLs vs just supporting one. The set of requirements to support "pokeapi.co/api" is a proper subset of the set of requirements to support "api.pokeapi.co" and "pokeapi.co/api" together. I don't see any benefit to the new URL.
So what do you suggest?
Well, so if the two endpoints will be supported forever we can just go with the two patterns. If we will switch from static content + Netlify to something else we will have to remember to keep the two endpoints.
So what do you suggest
The simple solution: deploy the pokeapi-co repo to one Netlify site. Deploy this repo to another Netlify site. Point the pokeapi.co domain to one site and add a redirect rule from there to the other. If we want to minimize redirects, we can point the domain to the api site and redirect for the non-api pages.
Ideally we'd have all our API requests run through a caching and rate limiting proxy anyway (does Cloudflare do that?).
Sounds like a solution to me. Perhaps by suggesting a change to the canonical URL, I and @tdmalone were trying to fix a potential problem that doesn't actually exist.
Anyway, I suppose this issue can be closed (further discussion about the redirect, etc. can happen in pokeapi#355 or in a new issue). It might still be a good idea to remove /api from the URLs in this repo for the benefit of people who choose to self-host, by simplifying the URL, but that's a very minor point and probably not something that really matters.
It might still be a good idea to remove /api from the URLs in this repo for the benefit of people who choose to self-host, by simplifying the URL, but that's a very minor point and probably not something that really matters.
I'd prefer to keep it there since it simplifies converting resource urls to local filesystem paths in Ditto a bit. Also, ditto analyze places an auto generated JSON schema under /data/schema/v2 right next to /data/api/v2. Eventually, I'd like ditto transform to add a reference to the appropriate schema inside each object in a "$schema" key and have those schemas served alongside the API.