So I’m trying to find a list of all the various ESI scopes that can be requested. This information seems to be poorly documented. Yes it might be documented in various places but to me it seems to be poorly done so I want to make sure I don’t miss anything. The places I know where to find the scopes that are valid for ESI are these two links:
Now I have a number of questions related to this. First, are the scopes listed on the CREST page valid for ESI data? Second, why isn’t there a page on the documentation site for the ESI scopes like there is for the CREST scopes? Third, it looks like all the scopes on the ESI page have a version associated with them, like .v1. If a v2 scope ever came out, currently on the ESI page it only lists v1 scopes so I’m guessing one doesn’t exist yet, would an application that requested a v1 scope have to have a user go through the SSO process again to request a v2 scope? Or would the application automatically have access to the v2 scope?
My last question, why doesn’t the ESI page list what scope each end-point requires? For instance, /characters/{character_id}/assets/ doesn’t list that it requires I assume to be the scope esi-assets.read_assets.v1 but just that it requires A scope. Wouldn’t it be better to list the specific scope required on each end-point to help developers create apps that only request the minimal permissions required?
I GUESS it is ok if you need to read the swagger.json to figure out all the possible scopes for ESI, but for someone completely new to ESI and OAuth in general, probably a good idea to detail that out somehow. Just saying that a “For new ESI developers” blog came out and it said nothing about scopes and you essentially need to dig around for possible scopes to figure it out.
Just trying to make this process easier for everyone who wants to develop apps for EVE.
possible scopes for ESI are all scopes with esi-, none other. They will probably be renamed etc, but not before CREST/XML are deprecated, shut down and removed (as some dev said iirc).
As for required scope per endpoint, it was known by hovering the lock in the swagger UI for ESI, but looks like it bugs. But you can also find them within the swagger spec directly yes.
if you go to esi.tech.ccp.is/ui in the top right is a lock. Click that and it should pop up a box with all the scopes.
If you go to esi.tech.ccp.is/latest and expand a scope that requires auth. There will be a red ! You can mouse over to see the scope. Or as stated before check the swagger.json
Looking at the scopes a little bit for ESI, sure seems like they could use some restructuring. For instance, the scope “esi-assets.read_assets.v1”, now you could assume it is for a character but why make it ambiguous? we already have esi-characters namespace so why not actually change it to esi-characters.read_assets.v1?
Then, you can put ‘esi-assets.read_corporation_assets.v1’ in its proper namespace of ‘esi-corporations.read_assets.v1’.
Of course, this would be where having a readthedocs page that is constantly updated would come in handle for changes like this. Or even a diff page for scopes like you do for the diff of the ESI Swagger page. The last issue would of course be how do you handle changing the scope required for something like this? I mean the data itself might not change or even the route, but the scope did so would you require people to give authentication to the new scope?
I think it’s very unlikely we will get scope renames. It’s simply more trouble than it’s worth.
The migration to the new scope names would be a nightmare and would require literately everyone to update their software to support the new scope names. To avoid breaking everyone’s software, you would need to support both the old and new scopes for while (maybe even forever: see CCPs mobile scope).
Scopes are mostly used in code, so, it’s not really that important anyway.
Someone have to maintain the documentation and keep the data up-to-date all the time (Wrong documentation is worse than no documentation).
Swagger is already self-documenting AKA all the data is already available in the swagger.json (It will always be the only place you can be 100% sure the information is up-to-date, anyway)
tl:dr I do not agree with that.
If you want to generate a list of all scopes, for yourself, I do have some code for that:
The code generate the following file:
You will have to modify the script a bit for your purpose, but, I think it’s a good start.
I think there are bigger fish to fry then renaming simple routes. Yes some aren’t as intuitive as we’d hope when someone new walks in the door and takes a look, but once you get your feet wet and familiarize yourself with it, that doesn’t matter nearly as much.
Both for endpoints and scopes adding a search function would solve most problems.
The endpoints could be ordered a lot better and I hope they do it at some point, it should be possible since routes are versioned. Even people who have worked with ESI since the beginning, may miss endpoint, that would have been useful to them, had they known they existed.
And it’s only going the get worse as more awesomeness is added, if just half of the features request are added over time, the amount of endpoints are going to end up being quite overwhelming…
Primarily because it’s going by endpoint groups first right now. Characters does not contain /characters/{character_id}/assets/ under it’s umbrella, it’s located instead under Assets
read assets for * (includes corporate if roles allow)
Just remember, if you think they should include assets under the Character umbrella, then they’d also have to include ANYTHING related to a character (market orders, wallets, journals, killmails, etc etc etc).