api-notebook
api-notebook copied to clipboard
mulesoft
Singular authenticate function for RAML client
Implement a singular authenticate function for generated RAML API clients.
@doolittle How does this method actually work? There are lots of variables to consider. What happens when no auth method has pre-defined keys? Do we just trigger the first auth flow? Do we throw an informative error?
@blakeembrey the spirit of the magic authenticate() method is improve the developer experience and quickly get them exploring the API.
With the modals, hard-coded application keys, and eventual token vault, we're abstracting authentication into a flow outside of the notebook. For documentation purposes--explaining to users how to explore APIs--it's easiest to just say "call the authenticate() method on the client and we'll take care of the rest."
"Taking care" of authentication would mean displaying the appropriate modals to get the user an authenticated client in the fewest possible steps. If we have have hard-coded tokens for the API, we'd be able to just display the authorization window from the API. If we need the user to input tokens, we'd show that modal. In the inspector, we could explain how we authorized the API for the user's benefit.
If we can't authenticate the user magically, we could error out gracefully and explain to the user how s/he needs to authenticate manually. It seems like we could cover most use cases with the magic method.
If there are too many nuances to consider, we can save this one until later when we're all in the office and can go through the use cases.
@usarid what do you think about a magic "authenticate()" method for an API client, instead of authenticateOAuth1(), authenticateOAuth2(), etc.?
I think it’s extremely worthwhile to spell out exactly the rules that the method would follow, based on all that the RAML spec allows (multiple auth schemes, with or without pre-provided keys), and make sure that’s all worked out.
With that, it’s a great method to have.
I would not have that instead of anything, but rather in addition to the explicit methods. It’s important for people to be able to explicitly model specific auth methods in addition to the smarts-endowed authenticate() method which may or may not end up calling the method they wanted. So authenticate() would simply have a decision tree and would invoke the specific auth methods.
On Dec 3, 2013, at 1:09 PM, Brad Bouse [email protected] wrote:
@blakeembrey the spirit of the magic authenticate() method is improve the developer experience and quickly get them exploring the API.
With the modals, hard-coded application keys, and eventual token vault, we're abstracting authentication into a flow outside of the notebook. For documentation purposes--explaining to users how to explore APIs--it's easiest to just say "call the authenticate() method on the client and we'll take care of the rest."
"Taking care" of authentication would mean displaying the appropriate modals to get the user an authenticated client in the fewest possible steps. If we have have hard-coded tokens for the API, we'd be able to just display the authorization window from the API. If we need the user to input tokens, we'd show that modal. In the inspector, we could explain how we authorized the API for the user's benefit.
If we can't authenticate the user magically, we could error out gracefully and explain to the user how s/he needs to authenticate manually. It seems like we could cover most use cases with the magic method.
If there are too many nuances to consider, we can save this one until later when we're all in the office and can go through the use cases.
@usarid what do you think about a magic "authenticate()" method for an API client, instead of authenticateOAuth1(), authenticateOAuth2(), etc.?
— Reply to this email directly or view it on GitHub.
@doolittle For the most part, the authenticate method is painful and I don't feel that it would do enough the smooth the potential differences in authentication methods. With that said, I have a simplistic working implementation ready. I really like the normal authenticate methods that are explicit and only open popups when needed. It feels like same in terms of flow and we won't incur any issues with trying to work out which flow to follow.
@doolittle Maybe the fallback could be a modal with a selection for the preferred API flow? In which case I would be happy to remove the old methods too and allow a manual selection to be passed as an argument. This would be awesome!
@blakeembrey isn't that implemented already? Sorry to bother you by the way ;)
I believe so, but we never finished the idea of having a global credential vault, etc.
Understand. If thats the case, I leave it open and we come back to that later.