Where should `has-permission` be accounted for?

[eporama]

There is an API endpoint for /account/applications/{applicationUuid}/has-permission which returns basically true or false if the account has access to a specific permission on a specific application.

Should this be a method in Account? Or in Permissions? Or… It doesn't really return an operation result, but an access response… Do we need a new AccessResponse class? Might be useful as there are other has-permission endpoints as well /account/teams/{teamUuid}/has-permission but those seem to be the only two.

They're both on the Account stub but might be more appropriate under Applications and Teams Endpoints respectively.

So before working on a PR, I figured I'd set a direction first.

[typhonius]

Hmm, good question. At an initial glance, I'd say we should try to stick to what would semantically make sense to someone writing a request. With that in mind, I think we might want to have it related to the Account class as that's what we're checking the permissions of:

$account = new Account($client);
if ($account->hasPermission('uuid', 'deploy to prod')) {
  // deploy code here
}

I think you raise a good point about there being two different endpoints though: application and team. Part of me says we should do hasApplicationPermission and hasTeamPermission but that doesn't look as aesthetic as a simple hasPermission or even can method.

We could of course get round that by allowing another parameter to hasPermission e.g. $account->hasPermission('application', 'uuid', 'deploy to prod'); but that wouldn't be optimal for unit testing because we'd require some additional logic in the method to determine which endpoint we're going to.

Finally, with the response we get, again you're right that we can't use an OperationResponse, so probably need an AccessResponse.

Ultimately I could probably be convinced of a few different directions at this point because there doesn't seem to be a clear-cut answer, but my gut does say it should revolve around Account because that's the thing we're ultimately asking the API for information on.

[typhonius]

Following up from this, we do have a few other endpoints in the account namespace that could benefit from a true/false response e.g. is-admin, is-owner for applications, teams, and orgs so maybe our proposed AccessResponse becomes more generic to handle the boolean we're receiving. Slightly annoyingly, the key that returns is different: admin, owner, and access...

[eporama]

One additional point to mention is that access isn't truly a boolean. If you do have the permission, you receive a 200 with "access: true" in the body response JSON.

If you do not have the permission, you receive a 403 response with

{
  "error": "forbidden",
  "message": "You do not have the 'example permission' permission for this application."
}

http://cloudapi-docs.acquia.com/#/Account/getAccountApplicationHasPermission

The 403 is not in reference to being able to ask the question… it's mean to be the response that you will not have that particular permission.